{ "openapi": "3.1.0", "info": { "title": "Dyflexis API", "summary": "REST API for the Dyflexis workforce management platform.", "version": "", "license": { "name": "Proprietary", "url": "https://dyflexis.com" }, "description": "Dyflexis is a complete **workforce management platform** that\nbrings staff scheduling, time tracking and attendance, leave and\nabsence, AI-powered demand forecasting, payroll, performance\nmanagement, skills management, and an employee hub with chat\ntogether in one system. The Dyflexis API gives you programmatic access to the\nworkforce data behind that platform, the (automated) staff\nplanning, time tracking, payrolling, absence management, workload\ninformation, and staff capacity that Dyflexis manages.\n\nEndpoints are organised by resource, **Employees**, **Contracts**,\n**Time clock**, **Payroll**, **Absence**, **Information streams**, and\nso on. The version of each endpoint (`v0`, `api2`, `v3`) lives in the\nURL; you can mix versions in the same integration.\n\n## Base URL\n\n```\nhttps://app.dyflexis.com/{systemName}\n```\n\nReplace `{systemName}` with the tenant identifier of the\ncustomer you are integrating with, the customer provides this\nvalue to you when they connect your integration (see the\n[`systemName` server variable](#section/Servers) below for\ndetails on where to find it). Every server URL in this\nspecification (and any new environment added in the future)\nstarts with this base; new environments extend it with\nadditional path segments rather than introducing a different\nhost. This is enforced by the `rule/server-url-base` lint\nassertion in `redocly.yaml`. Each version has its own URL\nprefix under that base:\n\n| Version | Prefix | Status |\n| --- | --- | --- |\n| v3 | `/api//v3/...` | Latest production, preferred for new integrations |\n| api2 (v2) | `/api2/...` | Stable production, use when no v3 equivalent exists |\n| v0 | `/api/v0/...` | Legacy, one endpoint kept for existing Business Intelligence consumers |\n\n## Authentication\n\nAlmost every endpoint requires an API key, sent in the\n`Authorization` header with the `Token` prefix:\n\n```\nAuthorization: Token YOUR_AUTH_TOKEN\n```\n\n`YOUR_AUTH_TOKEN` is the API key issued to you by Dyflexis.\n\nTo call an endpoint directly from these docs: open the\noperation, click **Try it**, and open the **Security** tab of\nthe request panel. **Name** is pre-filled with `Authorization`\nand **API key** with `Token YOUR_AUTH_TOKEN`; replace\n`YOUR_AUTH_TOKEN` with your API key, keeping the `Token `\nprefix. The key is kept in your browser's session storage only\nand is cleared when the session ends.\n\n### API scopes\n\nEach token is issued with one or more **scopes** that gate which\nparts of the API it can call. A scope is a named permission on the\ntoken (for example `business`, `clock`, `payroll`, `absence`,\n`external_employees`, `information_lines`); every operation\ndeclares the scope it requires, and the scope must be **enabled on\nyour token** before that operation will accept the request. A\ntoken without the required scope is rejected with `403 Forbidden`,\neven when the token itself is otherwise valid.\n\nScopes are issued per integration, you do not pick them yourself.\nAsk a Dyflexis administrator to enable the scopes you need when you request your\ntoken. The required scope is listed on each operation.\n\n## Timezones\n\nAll date and time values in this API are expressed in the\n**timezone configured on the customer's Dyflexis tenant**, not\nUTC and not the partner's local timezone. A shift returned as\nstarting at `09:00` starts at `09:00` in the customer's\nconfigured timezone, regardless of where your client is\nrunning, and a timestamp you send in is interpreted the same\nway. The tenant timezone is a per-customer setting; if you\nintegrate with customers in different countries, treat the\ntimezone as a per-tenant property and read or store it\nalongside the data you process.\n\n## Errors\n\nThe API returns standard HTTP status codes. Successful responses are\nin the `2xx` range; client errors in the `4xx` range; server errors in\nthe `5xx` range.\n\n| Code | Meaning |\n| --- | --- |\n| `200 OK` | Request succeeded |\n| `201 Created` | Resource created |\n| `400 Bad Request` | Validation failed or the payload was malformed |\n| `401 Unauthorized` | Missing or invalid authentication |\n| `403 Forbidden` | Token does not include the required scope |\n| `404 Not Found` | Resource or path does not exist |\n| `429 Too Many Requests` | Rate limit exceeded, back off and retry |\n| `500 Internal Server Error` | Unexpected server error |\n| `503 Service Unavailable` | Upstream system temporarily unavailable |\n\nError bodies are returned as `application/json` **only when the request\nsends an `Accept: application/json` header**; without it the API may\nreturn an HTML error page instead, so always send that header. A JSON\nerror body has the fields `title`, `status`, `detail`, `message` (the\nsame text as `detail`), and `code`. Validation failures (`400`) add a\n`violations` array with one entry per invalid field (`propertyPath`,\n`title`, `type`).\n\n## Rate limiting\n\nRequests are rate-limited per token. When a token exceeds the limit,\nrequests return `429 Too Many Requests`. Implement exponential backoff\non `429` and `5xx` responses, and avoid tight polling loops.\n\n## Pagination\n\nList endpoints paginate with a `page` query parameter (or a path\nsegment, depending on the version). Where supported, responses\ninclude a `_links` block with `self`, `next`, `prev`, `first`, and\n`last` URLs you can follow without recomputing.\n", "x-logo": { "url": "logo-dyflexis.svg", "altText": "Dyflexis" }, "contact": { "name": "Dyflexis", "email": "integrations@dyflexis.com", "url": "https://dyflexis.com" } }, "servers": [ { "url": "https://app.dyflexis.com/{systemName}", "description": "Production", "variables": { "systemName": { "default": "your-tenant", "description": "**Required.** The tenant identifier (also called the\n*system name*) of the customer envoirement you are integrating with.\n\nThe system name is set by Dyflexis when the customer's\nenvironment is created and is **provided to you by the\ncustomer** when they connect your integration, partners\ndo not pick or generate this value themselves. The same\nvalue is what the customer sees as the first path segment\nof their own Dyflexis URL\n(`https://app.dyflexis.com//...`), so if you\nare unsure of the value for a particular customer, ask\nthem or have them check their browser address bar. The\nsame system name is used for every endpoint on every API\nversion.\n\nThe default `your-tenant` shown here is a placeholder and\nmust be replaced with the customer's real system name\nbefore sending a request.\n" } } } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Offices & departments", "description": "Offices are the top-level organisational units in Dyflexis;\ndepartments are nested inside them. Use these endpoints to\ndiscover the offices you can write data against and to fetch the\nfull department tree of an office.\n" }, { "name": "Employees", "description": "Employees are the people working in your organisation. Use these\nendpoints to list employees; to map a Dyflexis employee to an external\npersonnel number; and to create or update an external employee\nrecord from your own HR or payroll system.\n\nThree list endpoints are exposed under different token scopes so\neach consumer sees only the data its scope is allowed to read:\n`business`, `clock`, and `payroll`.\n" }, { "name": "Employment contracts", "description": "Employment contracts describe an employee's terms of employment, \noffice, contract type, hours, salary, and validity period. Use\nthese endpoints to list available contract types and to push\ncontracts from your HR system into Dyflexis.\n" }, { "name": "Clocked hours", "description": "Record clock-in and clock-out events for an employee against a\nspecific clocking device. Both endpoints require the `clock`\ntoken scope.\n" }, { "name": "Registered hours", "description": "Registered hours are the **confirmed clocking time** for an\nemployee, after rounding rules and break-time deductions have\nbeen applied. They are derived from clocked or manually entered\ntime and represent the finalised, payable hours, distinct from\nthe raw clock-in/clock-out events.\n\nUse these endpoints to fetch registered hours, and to retrieve\nattendance registrations (the merged record of planned shifts\nand clocked hours) for a given date. Useful for reporting,\ntime-and-attendance dashboards, and reconciliation against\nscheduled hours.\n" }, { "name": "Scheduling", "description": "List scheduled shifts and the audit trail of schedule mutations\n(creations, modifications, deletions). The mutation feed is a\nlegacy v0 endpoint kept for existing Business Intelligence\nconsumers, there is no v3 equivalent yet.\n" }, { "name": "Payroll", "description": "The Payroll endpoints implement a **bi-directional flow**\nbetween an external payroll system and Dyflexis:\n\n- **Payroll → Dyflexis (employee sync).** The payroll system\n is typically the source of truth for the workforce.\n Employee and contract data can be synced from the payroll\n system into Dyflexis so that scheduling, time-tracking,\n and absence administration all operate on the same\n employee master that payroll uses. The endpoints for this\n direction live under\n [**Employees**](#tag/Employees) and\n [**Employment contracts**](#tag/Employment-contracts).\n- **Dyflexis → Payroll (confirmed hours).** Once a payroll\n period closes in Dyflexis, Dyflexis makes **all confirmed\n hour information** for that period, aggregated per day\n and per department, available for the payroll system to\n pick up and process. Each finalised period is published\n on a queue you poll and acknowledge, so no period is\n missed or processed twice.\n\nConcretely, this resource exposes hours aggregated per day\nand per department for a payroll period, the queue of\nfinalised payroll periods waiting to be picked up by an\nexternal payroll system, and the wage components that\nperiods produce.\n\nTypical export flow (Dyflexis → Payroll):\n\n1. Poll `GET /api2/payroll/queue/from/{lastQueueId}` for new items.\n2. For each item, fetch the period hours from\n `GET /api/payroll/v3/hours-per-day/...` or\n `GET /api/payroll/v3/hours-per-department/...`.\n3. Acknowledge the item with\n `POST /api2/payroll/queue/{queueId}/status`.\n" }, { "name": "Absence", "description": "Manage sick-leave registrations: list them, update their status\n(e.g. mark as recovered), and read the full status history of a\nsingle registration.\n" }, { "name": "Information streams", "description": "Information streams hold time-series **workload** and\n**capacity** data that drives forecasting and demand-based\nscheduling in Dyflexis.\n\n- **Workload** measures the amount of work that needs to be\n done in a given timeframe, for example \"covers per hour\" in\n a restaurant, \"transactions per hour\" in a retail store, or\n \"room occupancy per day\" in a hotel.\n- **Staff Capacity** is the staffing needed to execute the\n workload, the employees required expressed in hours or in\n costs.\n\nThe transformation from workload to capacity, deriving how\nmuch staff a given amount of work requires, can also be done\nin Dyflexis, so you can push raw workload and let Dyflexis\ncompute the capacity it implies. Use these endpoints to\nregister a stream, push data points into it, and read back\nwhat has been stored.\n\nThe `/information-streams/v3/...` family offers stream CRUD,\nbulk reads, and a configuration-driven data-point payload.\n\n### Onboarding flow\n\nWhen integrating a new information stream, follow these four\nphases in order:\n\n1. **Create the stream.** Register the stream with\n `POST /information-streams/v3/streams`, declaring its\n `type`, `unit`, `category`, `granularity`, and, optionally,\n the `departmentIds` it covers. Department IDs can be looked\n up by fetching the department tree with\n [`GET /api/department-management/v3/tree`](#tag/Offices-and-departments/operation/getDepartmentTree),\n which requires a token with the `business` scope in\n addition to the `forecasting` scope used by the\n information stream endpoints. The granularity is fixed at\n creation time and cannot be changed later, so pick the\n finest grain you can reliably supply (typically `hour`\n for hospitality, `day` for retail).\n2. **Backfill historical data.** Push every available\n realised data point from the past into the stream using\n `POST /information-streams/v3/datapoint/{key}`. **AI\n forecasting only becomes available once the stream holds\n at least 31 months of historical *realised* data**, so a\n backfill of that depth is a hard requirement before\n Dyflexis can forecast on top of the stream. Beyond that\n minimum, the more representative the history (ideally one\n or more full seasonal cycles), the better the forecast\n quality.\n3. **Push new data in (near) real time.** Once history is\n in, keep the stream current by sending new data points as\n soon as they are realised in the source system, ideally\n as each underlying period closes (end of hour, end of\n day, etc., depending on the configured granularity). At a\n minimum, re-push a **sliding window** of the most recent\n periods on a regular schedule (for example the last few\n days or weeks), so that any late-arriving corrections in\n the source system are reflected in the stream. Better\n still, update the information stream on every change to\n the underlying historical data, so the stream always\n mirrors the source of truth.\n4. **Understand roll-ups.** Verify that the data you pushed\n at the configured granularity rolls up correctly into the\n higher granularities your customer reports on in Dyflexis\n (see below).\n\n### Roll-ups\n\nRoll-ups happen **bottom up**: hour → day → week → month →\nquarter → year. Push data at the **lowest granularity you\nhave available** and Dyflexis aggregates it into every\ncoarser bucket automatically. The reverse is not true,\nsending only daily totals will not give you hourly detail\nlater, so always push at the finest grain the source\nsystem can produce.\n\n> **A \"work day\" is not always a calendar day.** A work\n> day in Dyflexis is the **operating day** the customer\n> uses to run their business, which can differ from the\n> calendar day that runs `00:00`-`23:59`. Many hospitality\n> customers stay open past midnight; for example, a bar\n> that opens on Friday at `19:00` and closes Saturday at\n> `04:00` is operating a single Friday shift, not two\n> separate days. In that case organisations prefer the\n> workload (e.g. `revenue`) realised between Saturday\n> `00:00` and `04:00` to be rolled up to **Friday**, not\n> Saturday, so that daily, weekly, and monthly totals match\n> how the business actually reports on itself.\n\nThe cut-over time between work days is configured per\noffice on the customer's tenant. As an integrator you do\nnot need to shift timestamps yourself, push each data point\nat the actual clock time it occurred and Dyflexis will roll\nit up to the correct work day.\n" }, { "name": "Employment agency", "description": "SETU-standard endpoints for staffing companies (employment\nagencies) integrating with Dyflexis. Implements the Dutch SETU\nXML standard for Human Resource, Assignment, and Time Card\nmessages. All endpoints accept and return `application/xml`\nand require the `setu` token scope.\n\nThese endpoints are versioned and hosted under\n`/api/setu/{version}/...`.\n" } ], "x-tagGroups": [ { "name": "Offices & departments", "tags": [ "Offices & departments" ] }, { "name": "Employees", "tags": [ "Employees" ] }, { "name": "Employment contracts", "tags": [ "Employment contracts" ] }, { "name": "Workload & capacity", "tags": [ "Information streams" ] }, { "name": "Scheduling", "tags": [ "Scheduling" ] }, { "name": "Time & attendance", "tags": [ "Clocked hours", "Registered hours" ] }, { "name": "Payroll", "tags": [ "Payroll" ] }, { "name": "Absence", "tags": [ "Absence" ] }, { "name": "Employment agency", "tags": [ "Employment agency" ] } ], "paths": { "/api/business/v3/employees": { "get": { "security": [ { "apiKey": [ "business" ] } ], "tags": [ "Employees" ], "operationId": "listBusinessEmployees", "summary": "List employees", "description": "**Requires scope:** `business`.\n\nFetches all active employees, their labels, and their card numbers.\n", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "name": "includeInactive", "in": "query", "description": "Also include inactive employees", "example": true, "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "link to current page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/employees?page=2" } } }, "next": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "link to next page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/employees?page=3" } } }, "prev": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "link to previous page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/employees?page=1" } } }, "first": { "type": "object", "properties": { "href": { "type": "string", "description": "link to first page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/employees?page=1" } } }, "last": { "type": "object", "properties": { "href": { "type": "string", "description": "link to last page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/employees?page=100" } } } } }, "pageCount": { "type": "integer", "description": "number of pages", "example": 100 }, "employees": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "integer", "description": "Internal employee id used by Dyflexis", "example": 1 }, "initials": { "type": [ "string", "null" ], "description": "Initials", "example": "J" }, "firstName": { "type": [ "string", "null" ], "description": "First name", "example": "Maria" }, "lastNamePrefix": { "type": [ "string", "null" ], "description": "Prefix", "example": "de" }, "lastName": { "type": [ "string", "null" ], "description": "Last name", "example": "Santos" }, "nameFormat": { "oneOf": [ { "$ref": "#/components/schemas/NameFormat" }, { "type": "null" } ], "description": "Null when no name format is set for the employee." }, "maritalStatus": { "oneOf": [ { "$ref": "#/components/schemas/MaritalStatus" }, { "type": "null" } ], "description": "Null when no marital status is set for the employee." }, "partnerInitials": { "type": [ "string", "null" ], "description": "Partner initials", "example": "A" }, "partnerFirstName": { "type": [ "string", "null" ], "description": "First name of partner", "example": "Anne" }, "partnerLastNamePrefix": { "type": [ "string", "null" ], "description": "Prefix of partner", "example": "van" }, "partnerLastName": { "type": [ "string", "null" ], "description": "Last name of partner", "example": "Ferguson" }, "gender": { "oneOf": [ { "$ref": "#/components/schemas/Gender" }, { "type": "null" } ], "description": "Null when no gender is set for the employee." }, "phoneNumber": { "type": [ "string", "null" ], "description": "Primary phone number", "example": "+31 6 12345678" }, "phoneNumber2": { "type": [ "string", "null" ], "description": "Secondary phone number", "example": "+31 20 5550100" }, "email": { "type": [ "string", "null" ], "description": "Email address", "example": "john.doe@example.com" }, "employmentStart": { "type": [ "string", "null" ], "description": "The first day of employment in ISO 8601", "example": "2026-12-31" }, "employmentEnd": { "type": "string", "description": "The last day of employment in ISO 8601, or the sentinel `0000-00-00` when employment is open-ended (no end date).", "example": "0000-00-00" }, "personnelNumber": { "type": [ "string", "null" ], "description": "The personnel number as known by the connecting party", "example": "HV-014" }, "costCenter": { "type": [ "string", "null" ], "description": "Cost center for the employee", "example": "Harborview Grand Hotel" }, "probationDate": { "type": [ "string", "null" ], "description": "The probationary period end date in ISO 8601", "example": "2026-12-31" }, "employerReferenceId": { "type": [ "string", "null" ], "description": "Unique employer reference identifier as known by the connecting party", "example": "HV-FD-014" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the label", "example": 10 }, "name": { "type": "string", "description": "Name of the label", "example": "Label 1" }, "showOnSchedule": { "type": "boolean", "description": "true if the label should be shown on the scheduling page", "example": true }, "groupId": { "type": "integer", "description": "Unique identifier of the group, where the label falls into", "example": 5 }, "groupName": { "type": "string", "description": "Name of the group, where the label falls into", "example": "Label 1" }, "endDate": { "anyOf": [ { "$ref": "#/components/schemas/Date" }, { "type": "null" } ], "description": "End date of the label for this employee" } } } }, "cardNumbers": { "type": "array", "description": "The card numbers associated with this employee", "items": { "type": "string", "example": "01234567" } } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Invalid page" } } } }, "/api2/employee-mappings": { "get": { "security": [ { "apiKey": [ "employee_mappings" ] } ], "tags": [ "Employees" ], "operationId": "listPersonnelNumbers", "summary": "List personnel numbers", "description": "**Requires scope:** `employee_mappings`.\n\n> **Legacy**, Kept for existing integrations. New integrations should use `GET /api/business/v3/employees`, which returns the same mapping (`employeeId` and `personnelNumber`) along with the full employee record.\n\nReturns a list of personnel numbers and their corresponding Dyflexis employee ids. Employees that do not have a personnel number will be omitted.\n", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "employeeMappings": { "type": "array", "items": { "type": "object", "properties": { "dyflexisId": { "type": "integer", "description": "The unique employee id used by Dyflexis", "example": 1 }, "personnelNumber": { "type": "string", "description": "The personnel number as known by the connecting party", "example": "243-a" } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } }, "x-badges": [ { "name": "LEGACY", "color": "#526fa6" } ] } }, "/api2/external-employees/{employeeReference}": { "post": { "security": [ { "apiKey": [ "external_employees" ] } ], "tags": [ "Employees" ], "operationId": "createOrUpdateEmployee", "summary": "Create or update an employee", "description": "**Requires scope:** `external_employees`.\n\nYou can use this endpoint to send employee data to Dyflexis. This will create an external employee in Dyflexis, or update an existing external employee if one with the same unique reference already exists.\n\nAn external employee will need to be connected to either an existing or a new Dyflexis employee within the Dyflexis application. An administrator can do this by using the widget in the employee overview page, or by using the external employee connection settings screen.\n\nOnce connected, the Dyflexis employee will be kept in sync with the external employee whenever data is sent to this endpoint.\n", "parameters": [ { "name": "employeeReference", "in": "path", "description": "Unique reference to the employee", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "lastName" ], "type": "object", "properties": { "initials": { "type": "string", "example": "J" }, "firstName": { "type": "string", "example": "Maria" }, "lastNamePrefix": { "type": "string", "example": "de" }, "lastName": { "type": "string", "example": "Santos" }, "nameFormat": { "$ref": "#/components/schemas/NameFormat" }, "maritalStatus": { "$ref": "#/components/schemas/MaritalStatus" }, "partnerInitials": { "type": "string", "example": "A" }, "partnerFirstName": { "type": "string", "example": "Anne" }, "partnerLastNamePrefix": { "type": "string", "example": "van" }, "partnerLastName": { "type": "string", "example": "Ferguson" }, "gender": { "$ref": "#/components/schemas/Gender" }, "phoneNumber": { "type": "string", "example": "+31 6 12345678", "description": "Primary phone number" }, "phoneNumber2": { "type": "string", "example": "+31 20 5550100", "description": "Secondary phone number" }, "email": { "$ref": "#/components/schemas/Email" }, "dateOfBirth": { "$ref": "#/components/schemas/Date" }, "placeOfBirth": { "type": "string", "example": "Pier 9 Bistro" }, "streetName": { "type": "string", "example": "Damrak" }, "streetNumber": { "type": "string", "example": "70" }, "postalCode": { "type": "string", "example": "1012 LM" }, "city": { "type": "string", "example": "Pier 9 Bistro" }, "nationality": { "type": "string", "example": "Portuguese" }, "employmentStart": { "$ref": "#/components/schemas/Date", "description": "The first day of employment" }, "employmentEnd": { "$ref": "#/components/schemas/Date", "description": "The last day of employment" }, "personnelNumber": { "type": "string", "description": "The personnel number as known by the connecting party", "example": "HV-014" }, "costCenter": { "type": "string", "description": "Cost center for the employee", "example": "Harborview Grand Hotel" }, "probationDate": { "$ref": "#/components/schemas/Date", "description": "The probationary period end date" }, "employerReferenceId": { "type": "string", "description": "Unique employer reference identifier as known by the connecting party", "example": "HV-FD-014" }, "jobDescription": { "type": "string", "description": "A textual description of the employee's job", "example": "Front desk receptionist" } } } } }, "required": true }, "responses": { "200": { "description": "Success. On a successful upsert the body is an empty JSON array. Data\nwarnings and errors are reported via the `400` response instead.\n", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Response code 400 - Bad request. Two outcomes are possible:\n\n- Warning: data may be incorrect but will still be accepted. Will empty any fields containing invalid data when linked to a Dyflexis employee.\n- Error: missing required data, the operation cannot continue and nothing will be saved.\n", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Warning", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "warning" ], "description": "Always \"warning\"." }, "data": { "type": "array", "items": { "type": "object", "required": [ "fieldName", "value" ], "properties": { "fieldName": { "type": "string", "description": "The name of the field that contained incorrect data." }, "value": { "type": "string", "description": "The value we tried to save." } } } } }, "example": { "status": "warning", "data": [ { "fieldName": "email", "value": "john@example" } ] } }, { "type": "object", "title": "Error", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "error" ], "description": "Always \"error\"." }, "data": { "type": "string", "description": "The error message. May be an empty string when no detail is provided." } }, "example": { "status": "error", "data": "" } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api2/contract-types": { "get": { "security": [ { "apiKey": [ "external_employees" ] } ], "tags": [ "Employment contracts" ], "operationId": "listContractTypes", "summary": "List contract types", "description": "**Requires scope:** `external_employees`.\n\nReturns a list of all available contract types\n", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "contractTypes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique contract type id used by Dyflexis", "example": 1 }, "name": { "type": "string", "description": "Contract type name", "example": "Hospitality permanent" }, "fixedBase": { "type": "boolean", "description": "Whether or not the contract type uses a fixed base", "example": true } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api2/external-employees/{employeeReference}/contracts": { "post": { "security": [ { "apiKey": [ "external_employees" ] } ], "tags": [ "Employment contracts" ], "operationId": "createOrUpdateContracts", "summary": "Create or update contracts", "description": "**Requires scope:** `external_employees`.\n", "parameters": [ { "name": "employeeReference", "in": "path", "description": "Unique reference to the employee", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contracts" } } } }, "responses": { "200": { "description": "Success. On a successful upsert the body is an empty JSON array. Data\nwarnings and errors are reported via the `400` response instead.\n", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Response code 400 - Bad request. Two outcomes are possible:\n\n- Warning: data may be incorrect but will still be accepted. Will skip all invalid contracts when linked to a Dyflexis employee.\n- Error: missing required data, the operation cannot continue and nothing will be saved.\n", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Warning", "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "warning" ], "description": "Always \"warning\"" }, "warnings": { "description": "Warning per contract", "type": "array", "items": { "type": "object", "properties": { "contractReference": { "type": "string", "description": "Unique contract reference" }, "type": { "description": "Warning type, either \"invalid_data\" or \"overlap\"", "oneOf": [ { "type": "string", "enum": [ "invalid_data", "overlap" ] } ] }, "data": { "description": "Validation detail for this contract. Depending on the warning\ntype and backend version this is either an object keyed by field\nname (with the offending values), or an array (invalid-field\nobjects for `invalid_data`, contract references for `overlap`).\n" } } } } } }, { "title": "Error", "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "error" ], "description": "Always \"error\"." }, "data": { "type": "string", "description": "The error message." } } } ] }, "examples": { "warning": { "value": { "status": "warning", "warnings": [ { "contractReference": "E01", "type": "invalid_data", "data": [ { "startDate": "20-111-0", "endDate": 102 } ] }, { "contractReference": "E02", "type": "overlap", "data": [ "E03", "E04" ] } ] } }, "error": { "value": { "status": "error", "data": "Missing employee reference." } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/department-management/v3/tree": { "get": { "security": [ { "apiKey": [ "business" ] }, { "apiKey": [ "payroll" ] } ], "tags": [ "Offices & departments" ], "operationId": "getDepartmentTree", "summary": "Fetch the department tree", "description": "**Requires scope:** `business` or `payroll`.\n\nRetrieves all organizational units (offices, department groups, and departments) in a hierarchical tree structure. For a hospitality group, this typically returns each hotel or restaurant as an office, with departments such as Front of House, Kitchen, Housekeeping, and Bar nested underneath.\n", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string" }, "type": { "type": "string", "description": "Defines the type of organizational unit", "example": "office", "enum": [ "office", "department_group", "department" ] }, "created": { "$ref": "#/components/schemas/UTC_DateTimeOrNull" }, "modified": { "$ref": "#/components/schemas/UTC_DateTimeOrNull" }, "addressId": { "type": [ "string", "null" ], "example": "1" }, "costCenterId": { "type": [ "string", "null" ], "example": "123" }, "costCenterName": { "type": [ "string", "null" ], "example": "Harborview Grand Hotel" }, "active": { "type": "boolean", "description": "Indicates whether the location is currently active", "example": true }, "departmentGroups": { "type": "array", "description": "An array representing department groups that belong to a specific location.", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string" }, "type": { "type": "string", "description": "Defines the type of organizational unit", "example": "department_group", "enum": [ "office", "department_group", "department" ] }, "created": { "$ref": "#/components/schemas/UTC_DateTimeOrNull" }, "modified": { "$ref": "#/components/schemas/UTC_DateTimeOrNull" }, "costCenterId": { "type": [ "string", "null" ], "example": "124" }, "costCenterName": { "type": [ "string", "null" ], "example": "Food & Beverage" }, "active": { "type": "boolean", "description": "Indicates whether the department group is currently active", "example": true }, "departmentGroups": { "type": "array", "description": "An array representing department groups that belong to a specific department group.", "items": { "type": "object" } }, "departments": { "type": "array", "description": "An array representing departments that belong to a specific department group.", "items": { "$ref": "#/components/schemas/Department" } } } } }, "departments": { "type": "array", "description": "An array representing departments that belong to a specific location.", "items": { "$ref": "#/components/schemas/Department" } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Not Found" } } } }, "/api2/offices": { "get": { "security": [ { "apiKey": [ "external_employees", "clock" ] } ], "tags": [ "Offices & departments" ], "operationId": "listOffices", "summary": "List offices", "description": "**Requires scope:** `external_employees` or `clock`.\n\n> **Legacy**, Kept for existing integrations. New integrations should use `GET /api/department-management/v3/tree`, which returns offices together with their department structure in one call.\n\nReturns a list of all available offices. This will not include department groups or departments.\n", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "offices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique office id used by Dyflexis, usable wherever the office id is needed", "example": 1 }, "name": { "type": "string", "description": "Name of the office", "example": "Harborview Grand Hotel" } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } }, "x-badges": [ { "name": "LEGACY", "color": "#526fa6" } ] } }, "/api/clock/v3/clock-in": { "post": { "security": [ { "apiKey": [ "clock" ] } ], "tags": [ "Clocked hours" ], "operationId": "registerClockIn", "summary": "Register a clock-in", "description": "**Requires scope:** `clock`.\n\nRegisters a clock in moment for an employee.\n", "requestBody": { "content": { "application/json": { "schema": { "required": [ "employeeId", "deviceId", "dateTime" ], "type": "object", "properties": { "employeeId": { "type": "integer", "example": 1 }, "deviceId": { "type": "string", "example": "POS-FRONTDESK-01", "minLength": 1, "maxLength": 35 }, "dateTime": { "$ref": "#/components/schemas/UTC_DateTime" }, "officeId": { "type": [ "integer", "null" ], "example": 1 } } } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/201" }, "400": { "$ref": "#/components/responses/400_v3" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/clock/v3/clock-out": { "post": { "security": [ { "apiKey": [ "clock" ] } ], "tags": [ "Clocked hours" ], "operationId": "registerClockOut", "summary": "Register a clock-out", "description": "**Requires scope:** `clock`.\n\nRegisters a clock out moment for an employee.\n", "requestBody": { "content": { "application/json": { "schema": { "required": [ "employeeId", "deviceId", "dateTime" ], "type": "object", "properties": { "employeeId": { "type": "integer", "example": 1 }, "deviceId": { "type": "string", "example": "POS-FRONTDESK-01", "minLength": 1, "maxLength": 35 }, "dateTime": { "$ref": "#/components/schemas/UTC_DateTime" }, "officeId": { "type": [ "integer", "null" ], "example": 1 } } } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/201" }, "400": { "$ref": "#/components/responses/400_v3" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api2/attendance-registration/{date}": { "get": { "security": [ { "apiKey": [ "attendance_registration" ] } ], "tags": [ "Clocked hours" ], "operationId": "listClockMoments", "summary": "List clock moments", "description": "**Requires scope:** `attendance_registration`.\n", "parameters": [ { "name": "date", "in": "path", "description": "Specifies the day to list the attendance registration for, in YYYY-MM-DD format", "example": "2026-12-31", "required": true, "schema": { "$ref": "#/components/schemas/Date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "attendanceRegistration": { "type": "array", "description": "Collection of attendance registrations", "items": { "type": "object", "properties": { "attendanceRegistrationId": { "type": "integer", "description": "Unique attendance registration id", "example": 123 }, "employeeId": { "type": "integer", "description": "Unique employee id", "example": 12345 }, "personnelNumber": { "type": "string", "description": "Personnel number", "example": "HV-FD-014" }, "dateTime": { "$ref": "#/components/schemas/DateTime" }, "event": { "$ref": "#/components/schemas/ClockEvent" }, "serialNumber": { "type": [ "string", "null" ], "description": "Serial number of the clock device that was used, or null for web/manual clock-ins.", "example": "POSFD01-9B7C2A" }, "deviceName": { "type": [ "string", "null" ], "description": "Name of the clock device that was used, or null for web/manual clock-ins.", "example": "POS-FRONTDESK-01" } } } } } } } } }, "400": { "description": "The date is well-formed but not a valid calendar date (e.g. `2026-13-40`)." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/business/v3/registered-hours": { "get": { "security": [ { "apiKey": [ "business" ] } ], "tags": [ "Registered hours" ], "operationId": "listRegisteredHours", "summary": "List registered hours", "description": "**Requires scope:** `business`.\n\nReturns a list of available registered hours\n", "parameters": [ { "name": "startDate", "in": "query", "description": "list registered hours that start from this date", "example": "2026-12-31", "required": false, "schema": { "$ref": "#/components/schemas/Date" } }, { "name": "endDate", "in": "query", "description": "list registered hours up until this date (end date inclusive)", "example": "2026-12-31", "required": false, "schema": { "$ref": "#/components/schemas/Date" } }, { "name": "officeId", "in": "query", "description": "the office the employee has a contract in", "example": 1, "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "link to current page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/registered-hours?page=2" } } }, "next": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "link to next page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/registered-hours?page=3" } } }, "prev": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "link to previous page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/registered-hours?page=1" } } }, "first": { "type": "object", "properties": { "href": { "type": "string", "description": "link to first page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/registered-hours?page=1" } } }, "last": { "type": "object", "properties": { "href": { "type": "string", "description": "link to last page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/registered-hours?page=100" } } } } }, "registeredHours": { "type": "array", "description": "Collection of all registered hours", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal hour id used by Dyflexis", "example": 1 }, "employeeId": { "type": "integer", "description": "Internal employee id used by Dyflexis", "example": 1 }, "personnelNumber": { "type": [ "string", "null" ], "description": "External employee id used by the client", "example": "HV-FD-014" }, "firstName": { "type": "string", "description": "First name", "example": "Maria" }, "infix": { "type": [ "string", "null" ], "description": "Infix (name particle), or null when the employee has none. May also be an empty string.", "example": "de" }, "lastName": { "type": "string", "description": "Last Name", "example": "Santos" }, "employeeCostCenter": { "type": [ "string", "null" ], "description": "The cost center associated with the employee", "example": "0052" }, "contractTypeId": { "type": "integer", "description": "Internal contract type id used by Dyflexis", "example": 123 }, "contractType": { "type": [ "string", "null" ], "description": "The name of the contract type the employee has", "example": "Hospitality permanent" }, "officeId": { "type": [ "integer", "null" ], "description": "The id of the office the hour has been registered for. For neutral hour types, which are not registered for specific offices, this will be the employee contract office.", "example": 1 }, "officeName": { "type": [ "string", "null" ], "description": "The name of the office the hour has been registered for. For neutral hour types, which are not registered for specific offices, this will be the employee contract office.", "example": "Harborview Grand Hotel" }, "departmentId": { "type": [ "integer", "null" ], "description": "The id of the department the hour has been registered for. For neutral hour types, which are not registered for specific departments, this will be null.", "example": 1 }, "departmentName": { "type": [ "string", "null" ], "description": "The name of the department the hour has been registered for. For neutral hour types, which are not registered for specific departments, this will be null.", "example": "Front Desk" }, "costCenterId": { "type": [ "integer", "null" ], "description": "The id of the cost center associated with the department the hour has been registered for. For neutral hour types, which are not registered for specific departments, this will be null.", "example": 1 }, "costCenterName": { "type": [ "string", "null" ], "description": "The name of the cost center associated with the department the hour has been registered for. For neutral hour types, which are not registered for specific departments, this will be null.", "example": "Name" }, "costCenterCode": { "type": [ "string", "null" ], "description": "The code of the cost center associated with the department the hour has been registered for. For neutral hour types, which are not registered for specific departments, this will be null.", "example": "code" }, "startDateTime": { "$ref": "#/components/schemas/DateTime" }, "endDateTime": { "$ref": "#/components/schemas/DateTime" }, "hourType": { "type": "string", "description": "The hour type of the registered hour", "example": "work" }, "hours": { "type": "number", "description": "The registered hours.", "example": 8.5 }, "status": { "$ref": "#/components/schemas/HourStatus" }, "breakMinutes": { "type": "integer", "description": "The break time of the hour in minutes, 0 if no break.", "example": 30 }, "duration": { "type": "integer", "description": "The registered time in minutes.", "example": 480 }, "kilometers": { "type": "number", "description": "Number of kilometers that have been registered at this time", "example": 10 }, "customExpenses": { "type": "array", "description": "Collection of all the custom expenses that have been registered at this time", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The System name of the expense", "example": "office_day" }, "value": { "type": [ "string", "integer", "boolean", "array" ], "items": { "type": [ "string", "integer" ] }, "description": "The value of the expense", "example": true } } } }, "remark": { "type": [ "string", "null" ], "description": "Remark of the register hour block" } } } }, "pageCount": { "type": "integer", "description": "number of pages", "example": 100 } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Invalid page" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/business/v3/scheduled": { "get": { "security": [ { "apiKey": [ "business" ] } ], "tags": [ "Scheduling" ], "operationId": "listScheduledShifts", "summary": "List scheduled shifts", "description": "**Requires scope:** `business`.\n\nReturns a list of available shifts\n", "parameters": [ { "name": "startDate", "in": "query", "description": "List shifts that start from this date", "example": "2026-12-31", "required": false, "schema": { "$ref": "#/components/schemas/Date" } }, { "name": "endDate", "in": "query", "description": "List shifts starting before this date (end date exclusive)", "example": "2026-12-31", "required": false, "schema": { "$ref": "#/components/schemas/Date" } }, { "name": "departmentId", "in": "query", "description": "The department the shifts should be scheduled in", "example": 3, "required": false, "schema": { "type": "integer" } }, { "name": "departmentGroupId", "in": "query", "description": "the department group the shifts should be scheduled in", "example": 2, "required": false, "schema": { "type": "integer" } }, { "name": "officeId", "in": "query", "description": "The office the shifts should be scheduled in", "example": 1, "required": false, "schema": { "type": "integer" } }, { "name": "includeOpenShifts", "in": "query", "description": "When true, it also returns open shifts", "example": true, "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "link to current page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/scheduled?page=2" } } }, "next": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "link to next page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/scheduled?page=3" } } }, "prev": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "link to previous page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/scheduled?page=1" } } }, "first": { "type": "object", "properties": { "href": { "type": "string", "description": "link to first page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/scheduled?page=1" } } }, "last": { "type": "object", "properties": { "href": { "type": "string", "description": "link to last page", "example": "https://app.dyflexis.com/{systemName}/api/business/v3/scheduled?page=100" } } } } }, "shifts": { "type": "array", "description": "Collection of all shifts", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal shift id used by Dyflexis", "example": 1 }, "employeeId": { "type": "integer", "description": "Internal employee id used by Dyflexis", "example": 1 }, "personnelNumber": { "type": "string", "description": "External employee id used by the client", "example": "HV-FD-014" }, "firstName": { "type": "string", "description": "First name", "example": "Maria" }, "infix": { "type": [ "string", "null" ], "description": "Infix (name particle), or null when the employee has none. May also be an empty string.", "example": "de" }, "lastName": { "type": "string", "description": "Surname", "example": "Santos" }, "contractTypeId": { "type": [ "integer", "null" ], "description": "Internal contract type id used by Dyflexis", "example": 123 }, "contractType": { "type": [ "string", "null" ], "description": "The name of the contract type the employee has", "example": "Hospitality permanent" }, "officeId": { "type": "integer", "description": "The id of the office the shift has been scheduled in", "example": 1 }, "officeName": { "type": "string", "description": "The name of the office the shift has been scheduled in", "example": "Harborview Grand Hotel" }, "departmentId": { "type": "integer", "description": "The id of the department the shift has been scheduled in", "example": 1 }, "departmentName": { "type": "string", "description": "The name of the department the shift has been scheduled in", "example": "Front Desk" }, "costCenterId": { "type": [ "integer", "null" ], "description": "The id of the cost center associated with the shift", "example": 1 }, "costCenterName": { "type": [ "string", "null" ], "description": "The name of the cost center associated with the shift", "example": "Name" }, "costCenterCode": { "type": [ "string", "null" ], "description": "The code of the cost center associated with the shift", "example": "code" }, "startDateTime": { "$ref": "#/components/schemas/DateTime" }, "endDateTime": { "$ref": "#/components/schemas/DateTime" }, "breakMinutes": { "type": "integer", "description": "The break time of the shift in minutes, 0 if no break.", "example": 30 }, "duration": { "type": "integer", "description": "The shift time in minutes.", "example": 480 }, "remark": { "type": "string", "description": "The shift remark, empty string if not used", "example": "Remark" }, "marking": { "type": "string", "description": "The shift marking, or an empty string when the shift has no marking.", "example": "sick", "enum": [ "", "leave", "sick", "standBy", "cancelled" ] }, "published": { "type": "boolean", "description": "Will show if the shift is published to the schedule" }, "isOpenShift": { "type": "boolean", "description": "True if the shift is open (not assigned to an employee)" } } } }, "pageCount": { "type": "integer", "description": "amount of pages", "example": 100 } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Invalid page" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v0/mutation": { "get": { "tags": [ "Scheduling" ], "operationId": "listScheduleMutations", "summary": "Schedule mutations", "description": "**Authentication:** legacy `X-Dyflexis-AuthToken` header (see the *Legacy v0 token* security scheme), not `Authorization`.\n\n> **Legacy**, Kept for existing Business Intelligence consumers. Avoid for new integrations; there is no v3 equivalent yet.\n\nReturns a list of changes in the schedule for the specified period, limits to 500 a page.\n", "security": [ { "XDyflexisAuthToken": [] } ], "parameters": [ { "name": "month", "in": "query", "schema": { "type": "integer" }, "description": "Required integer in the following range 1 <= integer <= 12", "example": 11 }, { "name": "year", "in": "query", "schema": { "type": "integer" }, "description": "Required integer in the following range 1 <= integer", "example": 2026 }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "api": { "type": "object", "description": "Metadata about the API call (server time, request timing, etc.)." }, "response": { "type": "object", "properties": { "data": { "type": [ "array", "null" ], "description": "The schedule mutation records, or null on error.", "items": { "type": "object", "description": "A schedule mutation record. Legacy v0 payload; see the example for its fields." } }, "expires": { "type": "string", "description": "Timestamp after which the response is considered stale." } } }, "error": { "type": [ "string", "null" ], "description": "Error message, or null on success. Authentication and other failures\nare returned as HTTP 200 with this field populated (for example\n`Invalid auth-token`); this endpoint does not use 4xx status codes.\n" } } }, "example": { "api": {}, "error": null, "response": { "data": [ { "id": 0, "user_id": 0, "date": "string", "change_date": "string", "change_by": "string", "changes": [ null ] } ], "expires": "2026-10-03T16:36:10.488Z" } } } } } }, "x-badges": [ { "name": "LEGACY", "color": "#526fa6" } ] } }, "/api/payroll/v3/employees": { "get": { "security": [ { "apiKey": [ "payroll" ] } ], "tags": [ "Payroll" ], "operationId": "listPayrollEmployees", "summary": "List payroll employees", "description": "**Requires scope:** `payroll`.\n\nFetches all active employees and their contracts. Returns up to 100 employees per page.\n", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "name": "includeInactive", "in": "query", "description": "Also include inactive employees", "example": true, "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "link to current page", "example": "https://app.dyflexis.com/{systemName}/api/payroll/v3/employees?page=2" } } }, "next": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "link to next page", "example": "https://app.dyflexis.com/{systemName}/api/payroll/v3/employees?page=3" } } }, "prev": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "link to previous page", "example": "https://app.dyflexis.com/{systemName}/api/payroll/v3/employees?page=1" } } }, "first": { "type": "object", "properties": { "href": { "type": "string", "description": "link to first page", "example": "https://app.dyflexis.com/{systemName}/api/payroll/v3/employees?page=1" } } }, "last": { "type": "object", "properties": { "href": { "type": "string", "description": "link to last page", "example": "https://app.dyflexis.com/{systemName}/api/payroll/v3/employees?page=100" } } } } }, "pageCount": { "type": "integer", "description": "number of pages", "example": 100 }, "employees": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "integer", "description": "Internal employee id used by Dyflexis", "example": 1 }, "initials": { "type": [ "string", "null" ], "description": "Initials", "example": "J" }, "firstName": { "type": [ "string", "null" ], "description": "First name", "example": "Maria" }, "lastNamePrefix": { "type": [ "string", "null" ], "description": "Prefix", "example": "de" }, "lastName": { "type": [ "string", "null" ], "description": "Last name", "example": "Santos" }, "nameFormat": { "oneOf": [ { "$ref": "#/components/schemas/NameFormat" }, { "type": "null" } ], "description": "Null when no name format is set for the employee." }, "maritalStatus": { "oneOf": [ { "$ref": "#/components/schemas/MaritalStatus" }, { "type": "null" } ], "description": "Null when no marital status is set for the employee." }, "partnerInitials": { "type": [ "string", "null" ], "description": "Partner initials", "example": "A" }, "partnerFirstName": { "type": [ "string", "null" ], "description": "First name of partner", "example": "Anne" }, "partnerLastNamePrefix": { "type": [ "string", "null" ], "description": "Prefix of partner", "example": "van" }, "partnerLastName": { "type": [ "string", "null" ], "description": "Last name of partner", "example": "Ferguson" }, "gender": { "oneOf": [ { "$ref": "#/components/schemas/Gender" }, { "type": "null" } ], "description": "Null when no gender is set for the employee." }, "phoneNumber": { "type": [ "string", "null" ], "description": "Primary phone number", "example": "+31 6 12345678" }, "phoneNumber2": { "type": [ "string", "null" ], "description": "Secondary phone number", "example": "+31 20 5550100" }, "email": { "type": [ "string", "null" ], "description": "Email address", "example": "john.doe@example.com" }, "dateOfBirth": { "type": [ "string", "null" ], "description": "Date of birth in ISO 8601", "example": "2026-12-31" }, "placeOfBirth": { "type": [ "string", "null" ], "description": "Location of birth", "example": "Lisbon" }, "streetName": { "type": [ "string", "null" ], "description": "Street name of current residence", "example": "Damrak" }, "streetNumber": { "type": [ "string", "null" ], "description": "House number of current residence", "example": "70" }, "postalCode": { "type": [ "string", "null" ], "description": "Postal code of current residence", "example": "1012 LM" }, "city": { "type": [ "string", "null" ], "description": "City of current residence", "example": "Amsterdam" }, "nationality": { "type": [ "string", "null" ], "description": "Nationality", "example": "Portuguese" }, "employmentStart": { "type": [ "string", "null" ], "description": "The first day of employment in ISO 8601", "example": "2026-12-31" }, "employmentEnd": { "type": "string", "description": "The last day of employment in ISO 8601, or the sentinel `0000-00-00` when employment is open-ended (no end date).", "example": "0000-00-00" }, "personnelNumber": { "type": [ "string", "null" ], "description": "The personnel number as known by the connecting party", "example": "HV-014" }, "costCenter": { "type": [ "string", "null" ], "description": "Cost center for the employee", "example": "Harborview Grand Hotel" }, "probationDate": { "type": [ "string", "null" ], "description": "The probationary period end date in ISO 8601", "example": "2026-12-31" }, "employerReferenceId": { "type": [ "string", "null" ], "description": "Unique employer reference identifier as known by the connecting party", "example": "HV-FD-014" }, "jobDescription": { "type": [ "string", "null" ], "description": "A textual description of the employee's job", "example": "Front desk receptionist" }, "employments": { "type": [ "array", "null" ], "description": "All the id's of the organizational units (see `GET /api/department-management/v3/tree`) where the employee is employed in. This value is null when there are no employments.", "items": { "type": "integer", "example": 10 } }, "contracts": { "type": "array", "items": { "type": "object", "properties": { "contractReference": { "type": [ "string", "null" ], "description": "Unique reference to the contract per employee. This could be a serial number or a unique id provided by an external system.", "example": "123abc" }, "officeId": { "type": "integer", "description": "Identifier of the Dyflexis office", "example": 1 }, "type": { "type": [ "integer", "null" ], "description": "Identifier of the Dyflexis contract type", "example": 1 }, "start": { "$ref": "#/components/schemas/Date", "description": "Start date of contract in ISO 8601" }, "end": { "$ref": "#/components/schemas/Date", "description": "End date of contract in ISO 8601, or the sentinel `9999-12-31` for an open-ended contract." }, "hoursPerWeek": { "type": [ "number", "null" ], "description": "Contractual hours the employee works in a workweek", "example": 40 }, "daysPerWeek": { "type": [ "number", "null" ], "description": "Average days the employee works in a workweek", "example": 5 }, "hourlySalary": { "type": [ "number", "null" ], "description": "Remuneration for employment per hour", "example": 20 }, "raise": { "type": [ "number", "null" ], "description": "Raise given to the employee", "example": 5 }, "maxHoursPerWeek": { "type": [ "number", "null" ], "description": "Max hours the employee works in a workweek.", "example": 50 } } } }, "customFields": { "type": "array", "description": "Custom fields with their label and value. Empty array when none are configured.", "items": { "type": "object" }, "example": [] } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Invalid page" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/payroll/v3/hours-per-day/{officeUrl}/{contractTypeGroupName}/{period}": { "get": { "security": [ { "apiKey": [ "payroll" ] } ], "tags": [ "Payroll" ], "operationId": "getHoursPerDay", "summary": "Fetch hours per day", "description": "**Requires scope:** `payroll`.\n\nReturns a list of all hours, allowances, and expenses in the requested locked payroll period.\nOnly days that have either hours, allowances or expenses will be included.\n", "parameters": [ { "name": "officeUrl", "in": "path", "description": "Slug of the office you wish to request the payroll information for", "example": "harborview-grand-hotel", "required": true, "schema": { "type": "string" } }, { "name": "contractTypeGroupName", "in": "path", "description": "Name of the contract type group for the payroll period", "example": "hospitality-permanent", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "path", "description": "The label of the payroll period you wish to request the payroll information for", "example": "2026-M02", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "description": "Meta information about the request", "properties": { "id": { "type": "integer", "description": "The unique result id for this period. Note that this will change when a period gets unlocked and locked again.", "example": 1 }, "office": { "type": "object", "description": "Information about the office for which the period was requested", "properties": { "id": { "type": "integer", "description": "The internal ID of the office", "example": 1 }, "name": { "type": "string", "description": "The name of the office", "example": "Pier 9 Bistro" } } }, "contractTypeGroupName": { "type": "string", "example": "Hospitality permanent", "description": "The unique contract type group id used by Dyflexis. Note that this is not the same as a contract type id." }, "period": { "type": "object", "description": "Information about the period itself", "properties": { "startDate": { "type": "string", "description": "The start date of the payroll period", "example": "2026-06-01" }, "endDate": { "type": "string", "description": "The end date of the payroll period", "example": "2026-06-30" }, "year": { "type": "integer", "description": "The year of the payroll period" }, "name": { "type": "string", "example": "M06", "description": "The period identifier as configured for your system" }, "targetPeriod": { "type": "integer", "example": 7, "description": "The period (month/week/etc) the payroll data needs to be sent to" }, "targetYear": { "type": "integer", "example": 2026, "description": "The year the payroll data needs to be sent to" } } } } }, "payroll": { "description": "The payroll hours/allowances/expenses, listed for each employee.", "type": "array", "items": { "type": "object", "properties": { "employee": { "type": "object", "description": "The employee to whom the hours belong", "properties": { "id": { "type": "integer", "description": "The unique employee id used by Dyflexis", "example": 1 }, "employeeReference": { "type": [ "string", "null" ], "description": "Unique reference to the employee when connected to an external employee that has been created using the [Create or update an employee](../#tag/Employees/operation/Create%20or%20update%20an%20employee) endpoint.", "example": "P1413B" }, "personnelNumber": { "type": "string", "description": "The personnel number as known by the connecting party", "example": "1413" }, "firstName": { "type": [ "string", "null" ], "example": "Gail" }, "lastName": { "type": [ "string", "null" ], "example": "Boehm" }, "lastNamePrefix": { "type": [ "string", "null" ] }, "employerReferenceId": { "type": [ "string", "null" ], "example": "123", "description": "The reference number for the employer" }, "costCenter": { "type": [ "string", "null" ], "example": "tech", "description": "The cost center for the employee" }, "employmentStart": { "type": [ "string", "null" ], "format": "date", "example": "2026-01-01", "description": "The employment start date (ISO 8601 date) for the employee" }, "employmentEnd": { "type": [ "string", "null" ], "format": "date", "example": "2026-12-31", "description": "The employment end date (ISO 8601 date) for the employee" } } }, "hours": { "description": "All the hours for the requested payroll application", "type": "array", "items": { "type": "object", "description": "The number of hours in the requested period for this employee.", "properties": { "date": { "$ref": "#/components/schemas/Date" }, "components": { "additionalProperties": { "type": "number" }, "example": { "work": 8, "break": 0.5, "Allowance.150": 27, "Allowance.ORTSpecial": 12 } } } } } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/payroll/v3/hours-per-department/{officeUrl}/{contractTypeGroupName}/{period}": { "get": { "security": [ { "apiKey": [ "payroll" ] } ], "tags": [ "Payroll" ], "operationId": "getHoursPerDepartment", "summary": "Fetch hours per department", "description": "**Requires scope:** `payroll`.\n\nReturns a list of all hours, allowances, and expenses in the requested locked payroll period, grouped by department.\nFor the neutral hour types, for example sickness, leave or all the allowances are grouped by the primary department of the employee.\nOnly days that have hours, allowances, or expenses will be included.\n", "parameters": [ { "name": "officeUrl", "in": "path", "description": "Slug of the office you wish to request the payroll information for.", "example": "harborview-grand-hotel", "required": true, "schema": { "type": "string" } }, { "name": "contractTypeGroupName", "in": "path", "description": "Name of the contract type group for the payroll period.", "example": "hospitality-permanent", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "path", "description": "The label of the payroll period you wish to request the payroll information for.", "example": "2026-M02", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "description": "Meta information about the request.", "properties": { "id": { "type": "integer", "description": "The unique result id for this period. Note that this will change when a period gets unlocked and locked again.", "example": 1 }, "office": { "type": "object", "description": "Information about the office for which the period was requested.", "properties": { "id": { "type": "integer", "description": "The internal id of the office.", "example": 1 }, "name": { "type": "string", "description": "The name of the office.", "example": "Pier 9 Bistro" }, "costCenter": { "type": [ "object", "null" ], "description": "Information about the cost center associated with the office.", "properties": { "id": { "type": [ "integer", "null" ], "description": "The unique cost center id.", "example": 1 }, "name": { "type": [ "string", "null" ], "description": "The name of the cost center.", "example": "Support" }, "code": { "type": [ "string", "null" ], "description": "The code of the cost center.", "example": "123" } } } } }, "contractTypeGroupName": { "type": "string", "example": "Hospitality permanent", "description": "The unique contract type group id used by Dyflexis. Note that this is not the same as a contract type id." }, "period": { "type": "object", "description": "Information about the period itself.", "properties": { "startDate": { "type": "string", "description": "The start date (ISO 8601 date) of the payroll period.", "example": "2026-06-01" }, "endDate": { "type": "string", "description": "The end date (ISO 8601 date) of the payroll period.", "example": "2026-06-30" }, "year": { "type": "integer", "description": "The year of the payroll period." }, "name": { "type": "string", "example": "M06", "description": "The period identifier as configured for your system." }, "targetPeriod": { "type": "integer", "example": 7, "description": "The period (month/week/etc) the payroll data needs to be sent to." }, "targetYear": { "type": "integer", "example": 2026, "description": "The year the payroll data needs to be sent to." } } } } }, "payroll": { "description": "The payroll hours/allowances/expenses, listed for each employee and grouped by day and department.", "type": "array", "items": { "type": "object", "properties": { "employee": { "type": "object", "description": "The employee to whom the hours belong.", "properties": { "id": { "type": "integer", "description": "The unique employee id used by Dyflexis.", "example": 1 }, "employeeReference": { "type": [ "string", "null" ], "description": "Unique reference to the employee when connected to an external employee that has been created using the [Create or update an employee](../#tag/Employees/operation/Create%20or%20update%20an%20employee) endpoint.", "example": "P1413B" }, "personnelNumber": { "type": "string", "description": "The personnel number as known by the connecting party.", "example": "1413" }, "firstName": { "type": [ "string", "null" ], "example": "Gail" }, "lastName": { "type": [ "string", "null" ], "example": "Boehm" }, "lastNamePrefix": { "type": [ "string", "null" ] }, "employerReferenceId": { "type": [ "string", "null" ], "example": "123", "description": "The reference number for the employer." }, "costCenter": { "type": [ "string", "null" ], "example": "tech", "description": "The cost center for the employee." }, "employmentStart": { "type": [ "string", "null" ], "example": "2026-01-01", "description": "The employment start date (ISO 8601 date) for the employee." }, "employmentEnd": { "type": [ "string", "null" ], "example": "2026-12-31", "description": "The employment end date (ISO 8601 date) for the employee." } } }, "hours": { "description": "All the hours for the requested payroll application, grouped by employee and department.", "type": "array", "items": { "type": "object", "description": "The number of hours in the requested period for this employee and department.", "properties": { "date": { "$ref": "#/components/schemas/Date" }, "department": { "type": [ "object", "null" ], "description": "Information about the department for which the hours were registered. (Nullable).", "properties": { "id": { "type": [ "integer", "null" ], "description": "The unique department id.", "example": 2 }, "name": { "type": [ "string", "null" ], "description": "The name of the department.", "example": "Support" }, "costCenter": { "type": [ "object", "null" ], "description": "Information about the cost center associated with the department.", "properties": { "id": { "type": [ "integer", "null" ], "description": "The unique cost center id.", "example": 1 }, "name": { "type": [ "string", "null" ], "description": "The name of the cost center.", "example": "Support" }, "code": { "type": [ "string", "null" ], "description": "The code of the cost center.", "example": "123" } } } } }, "office": { "type": "object", "description": "Information about the office where the hours were registered.", "properties": { "id": { "type": "integer", "description": "The unique office id.", "example": 1 }, "name": { "type": "string", "description": "The name of the office.", "example": "Den-Haag" }, "costCenter": { "type": "object", "description": "Information about the cost center associated with the office.", "properties": { "id": { "type": [ "integer", "null" ], "description": "The unique cost center id.", "example": 1 }, "name": { "type": [ "string", "null" ], "description": "The name of the cost center.", "example": "Main" }, "code": { "type": [ "string", "null" ], "description": "The code of the cost center.", "example": "12" } } } } }, "components": { "type": "object", "description": "The components of the hours and/or allowances for this employee and department.", "additionalProperties": { "type": "number" }, "example": { "work": 8, "break": 0.5, "Allowance.150": 27, "Allowance.ORTSpecial": 12 } } } } } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/api2/payroll/wage-components": { "get": { "security": [ { "apiKey": [ "payroll_hours" ] } ], "tags": [ "Payroll" ], "operationId": "listWageComponents", "summary": "List wage components", "description": "**Requires scope:** `payroll_hours`.\n\nLists all available wage components with their user friendly display names.\nThis list can be used as an aid in mapping the wage component fields to their corresponding fields in other systems.\n\nWage components are defined by using the wage component dropdown for columns in the Chronos sheet.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "wageComponents": { "type": "array", "items": { "type": "object", "properties": { "displayName": { "type": "string", "description": "The user friendly name of the component" }, "wageComponent": { "type": "string", "description": "The system name of the component" } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api2/payroll/queue/from/{lastQueueId}": { "get": { "security": [ { "apiKey": [ "payroll_hours" ] } ], "tags": [ "Payroll" ], "operationId": "getPayrollPeriodQueue", "summary": "Fetch the payroll period queue", "description": "**Requires scope:** `payroll_hours`.\n\nDyflexis allows the user to \"send\" a locked payroll period for external processing. These payroll periods are then added to a queue which you can fetch using this endpoint.\n\nEach entry in this list has a unique queue id and a URL you can use to fetch the payroll information.\n\nThe endpoint will list all queue items that have been created after `lastQueueId`, limited to a maximum of 10 items, so you can easily see whether there are new queue items to process.\nUse `0` as `lastQueueId` to get the very first 10 queue items.\n\nYou will need to keep track of which queue ids you have already processed in order to prevent processing remuneration information more than once.", "parameters": [ { "name": "lastQueueId", "in": "path", "description": "Queue id of the last item you processed; the response contains only items with a higher id. Use 0 on the first call.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollPeriodQueue": { "type": "array", "items": { "type": "object", "properties": { "queueId": { "type": "integer", "description": "Unique id for this dataset", "example": 1 }, "created": { "type": "string", "description": "Dataset creation date and time", "example": "2026-08-13 11:55:07" }, "officeId": { "type": "integer", "description": "Unique identifier of the office.", "example": 1 }, "officeName": { "type": "string", "description": "Slug of the office name.", "example": "office-name" }, "status": { "type": [ "string", "null" ], "description": "Last known status for this queue entry", "example": "in progress" }, "url": { "type": "string", "description": "Fully-qualified URL to GET the payroll period hours for this item. Points at the `/api2/payroll/hours/{office}/{contractTypeGroup}/{period}` endpoint.", "example": "https://app.dyflexis.com/{systemName}/api2/payroll/hours/harborview-grand-hotel/hospitality-permanent/2026-P01" }, "statusUpdateUrl": { "type": "string", "description": "Fully-qualified URL to POST a status update for this item. This is the `url` value with `/status` appended (`/api2/payroll/hours/{office}/{contractTypeGroup}/{period}/status`).", "example": "https://app.dyflexis.com/{systemName}/api2/payroll/hours/harborview-grand-hotel/hospitality-permanent/2026-P01/status" } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api2/payroll/queue/{queueId}/status": { "post": { "security": [ { "apiKey": [ "payroll_hours" ] } ], "tags": [ "Payroll" ], "operationId": "updatePayrollQueueStatus", "summary": "Update queue item status", "description": "**Requires scope:** `payroll_hours`.\n\nYou can update the status of a queue item in Dyflexis when processing the payroll period queue.\nThe status is displayed in the Dyflexis payroll page.", "parameters": [ { "name": "queueId", "in": "path", "description": "The queue item id for which to update the status", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "status", "application" ], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/PayrollStatus" }, "application": { "type": "string", "description": "An external application identifier. This allows multiple applications to process queue items and send individual status updates." }, "message": { "maxLength": 1000, "type": "string", "description": "The reason for this status", "example": "Invalid contract for user 125" }, "url": { "maxLength": 255, "type": "string", "description": "URL for more information about this status", "example": "https://www.example-payrollapplication.com/api-processing/error/1234-AA9D" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "payrollPeriodStatus": { "type": "object", "properties": { "queueId": { "type": "integer" }, "application": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" }, "url": { "type": "string" } } } } } } } }, "400": { "description": "Invalid status" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Invalid queue item id" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/absence/v3/sick-leave/{sickLeaveRegistrationId}/status-history": { "get": { "security": [ { "apiKey": [ "absence" ] } ], "tags": [ "Absence" ], "operationId": "getSickLeaveStatusHistory", "summary": "Get sick leave status history", "description": "**Requires scope:** `absence`.\n\nReturns the full status transition history for a sick leave registration, ordered\nchronologically (earliest first). Each entry represents a status change that occurred\nduring webhook processing or as reported by the external integration partner.\n", "parameters": [ { "name": "sickLeaveRegistrationId", "in": "path", "description": "The ULID of the sick leave registration.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" }, "example": "01GYS27FFVTP63WGPV34V1WR6P" } ], "responses": { "200": { "description": "OK. Returns an empty array if no status history exists.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The status at this point in time.", "enum": [ "new", "acknowledged", "in_progress", "success", "failed" ], "example": "acknowledged" }, "message": { "type": [ "string", "null" ], "description": "An optional message associated with this status change.", "example": null }, "externalReference": { "type": [ "string", "null" ], "description": "An optional external reference identifier from the integration partner.", "example": "EXT-2026-001234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The timestamp when this status was recorded.", "example": "2026-03-30T14:30:00+00:00" } } } } } } }, "400": { "description": "Invalid sick leave registration ID format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid sick leave registration ID format" } } } } } }, "401": { "$ref": "#/components/responses/401" } } } }, "/api/absence/v3/sick-leave": { "get": { "security": [ { "apiKey": [ "absence" ] } ], "tags": [ "Absence" ], "operationId": "listSickLeaveRegistrations", "summary": "List sick leave registrations", "description": "**Requires scope:** `absence`.\n\nReturns a list of sick leave registrations.\n", "parameters": [ { "name": "startDate", "in": "query", "description": "List sick leave registrations that end after this date.", "example": "2026-12-31", "required": false, "schema": { "$ref": "#/components/schemas/Date" } }, { "name": "endDate", "in": "query", "description": "List sick leave registrations starting before this date.", "example": "2026-12-31", "required": false, "schema": { "$ref": "#/components/schemas/Date" } }, { "name": "officeSlug", "in": "query", "description": "The office name the employee has a contract in.", "example": "harborview-grand-hotel", "required": false, "schema": { "type": "string" } }, { "name": "contractGroupLabel", "in": "query", "description": "The contract type name the employee has a contract in.", "example": "hospitality-permanent", "required": false, "schema": { "type": "string" } }, { "name": "sortField", "in": "query", "description": "The field to sort the result by. For now this only accepts \"startDate\".", "example": "startDate", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "In which direction to sort the results. only allowed values are `desc` (descending) and `asc` (ascending).", "example": "desc", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/Page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "Link to current page.", "example": "https://app.dyflexis.com/{systemName}/api/absence/v3/sick-leave?page=2" } } }, "next": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "Link to next page.", "example": "https://app.dyflexis.com/{systemName}/api/absence/v3/sick-leave?page=3" } } }, "prev": { "type": "object", "properties": { "href": { "type": [ "string", "null" ], "description": "Link to previous page.", "example": "https://app.dyflexis.com/{systemName}/api/absence/v3/sick-leave?page=1" } } }, "first": { "type": "object", "properties": { "href": { "type": "string", "description": "Link to first page.", "example": "https://app.dyflexis.com/{systemName}/api/absence/v3/sick-leave?page=1" } } }, "last": { "type": "object", "properties": { "href": { "type": "string", "description": "Link to last page.", "example": "https://app.dyflexis.com/{systemName}/api/absence/v3/sick-leave?page=100" } } } } }, "pageCount": { "type": "integer", "description": "Number of pages.", "example": 100 }, "sickLeaveRegistrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the sick leave registration.", "example": "01GYS27FFVTP63WGPV34V1WR6P" }, "employeeId": { "type": "integer", "description": "The id of the employee", "example": 12 }, "personnelNumber": { "type": [ "string", "null" ], "description": "The personnel number of the employee or null if no personnel number exists.", "example": "23V600" }, "startDate": { "$ref": "#/components/schemas/Date", "description": "Start date of sick leave in ISO 8601." }, "expectedEndDate": { "$ref": "#/components/schemas/Date", "description": "The expected end date of sick leave in ISO 8601." }, "endDate": { "type": [ "string", "null" ], "description": "The actual registered end date of sick leave in ISO 8601, or null if no end date has been specified.", "example": "2026-12-31" }, "remark": { "type": "string", "description": "The remark of the sick leave registration.", "example": "sore throat" }, "recovered": { "type": "boolean", "description": "Will show if the sick leave registration is closed and the employee is recovered." }, "sickDays": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the sick leave registration day.", "example": "01GYS27FFVTP63WGPV34V1WR6P" }, "date": { "$ref": "#/components/schemas/Date", "description": "The date of the sick day in ISO 8601." }, "hourType": { "type": "string", "description": "The specified hour type for that day.", "example": "standard sick leave" } } } } } } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Invalid page" } } } }, "/api/absence/v3/sick-leave/{sickLeaveRegistrationId}/status": { "post": { "security": [ { "apiKey": [ "absence" ] } ], "tags": [ "Absence" ], "operationId": "reportSickLeaveStatus", "summary": "Report sick leave status", "description": "**Requires scope:** `absence`.\n\nReport a status update for a sick leave registration. This endpoint is used by external\nintegration partners to report the processing status of a sick leave registration that\nwas sent via webhook.\n\nThe status transitions follow a state machine:\n- `in_progress`, The registration is being processed by the external system.\n- `success`, The registration was successfully processed (terminal state).\n- `failed`, The registration failed to process. Can be retried by sending a new status.\n\nNote: The initial statuses `new` and `acknowledged` are set automatically by Dyflexis\nwhen the webhook is sent and received. Only `in_progress`, `success`, and `failed`\ncan be reported via this endpoint.\n", "parameters": [ { "name": "sickLeaveRegistrationId", "in": "path", "description": "The ULID of the sick leave registration.", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" }, "example": "01GYS27FFVTP63WGPV34V1WR6P" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "The status to report.", "enum": [ "in_progress", "success", "failed" ], "example": "success" }, "message": { "type": [ "string", "null" ], "description": "An optional message providing details about the status (e.g. error details on failure). Maximum 1000 characters.", "example": "Successfully imported into external system.", "maxLength": 1000 }, "externalReference": { "type": [ "string", "null" ], "description": "An optional external reference identifier from the integration partner's system. Maximum 255 characters.", "example": "EXT-2026-001234", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Status reported successfully." }, "400": { "description": "Invalid request body, invalid ULID format, or unsupported status value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "The \"status\" field must be one of [in_progress, success, failed], \"unknown\" given" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "description": "No status record found for the given sick leave registration. This means no webhook has been sent for this registration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Sick leave registration status not found for the given sick leave registration" } } } } } }, "422": { "description": "Invalid state transition. For example, trying to report `in_progress` on a registration that is already in `success` state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Cannot transition from \"success\" to \"in_progress\"" } } } } } } } } }, "/information-streams/v3/list": { "get": { "security": [ { "apiKey": [ "forecasting" ] } ], "tags": [ "Information streams" ], "operationId": "listInformationStreams", "summary": "List information streams", "description": "**Requires scope:** `forecasting`.\n\nReturns information streams available to the authenticated token (scoped by the location selection logic).\n\nFiltering is supported via query parameters. List parameters (`departmentIds`, `categories`, `types`, `units`)\nare provided as comma-separated values.\n\nIf `groupBy` is provided, the response shape changes to a grouped payload.\n", "parameters": [ { "name": "category", "in": "query", "description": "Single information stream category to filter by.", "required": false, "schema": { "type": "string", "enum": [ "realized", "forecast", "budget" ] } }, { "name": "search", "in": "query", "description": "Search term to filter information streams by name.", "required": false, "schema": { "type": "string" } }, { "name": "groupBy", "in": "query", "description": "Group information streams by a specific field.", "required": false, "schema": { "type": "string", "enum": [ "category", "department" ] } }, { "name": "officeId", "in": "query", "description": "Filter information streams by location identifier.", "required": false, "schema": { "type": "integer" } }, { "name": "departmentIds", "in": "query", "description": "Comma-separated list of department identifiers.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "categories", "in": "query", "description": "Comma-separated list of categories to filter by.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "realized", "forecast", "budget" ] } } }, { "name": "types", "in": "query", "description": "Comma-separated list of stream types to filter by.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "units", "in": "query", "description": "Comma-separated list of units to filter by.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400-2" }, "401": { "$ref": "#/components/responses/401-2" }, "403": { "$ref": "#/components/responses/403-2" } } } }, "/information-streams/v3/data-points": { "get": { "security": [ { "apiKey": [ "forecasting" ] } ], "tags": [ "Information streams" ], "operationId": "listInformationStreamDataPoints", "summary": "Fetch information stream data points", "description": "**Requires scope:** `forecasting`.\n\nReturns data points for a single information stream.\n\nThe timestamps specify the lower bound of the time window, where the window is `granularity` long.\nFor example, if `granularity=\"hour\"`, the value at \"2026-04-02 11:00:00\" indicates the value between\n\"2026-04-02 11:00:00\" and \"2026-04-02 12:00:00\".\n\nIf `granularity` is not provided, the configured granularity of the information stream will be used.\n", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Information stream identifier (stream key) to filter by. Required:\nomitting it currently results in a `500` rather than a `400`.\n", "example": "covers-per-hour-pier9", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "description": "Start date of the information stream data in YYYY-MM-DD format", "required": true, "example": "2026-06-01", "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "description": "End date of the information stream data in YYYY-MM-DD format", "required": true, "example": "2026-06-30", "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "description": "Granularity of the information stream data to group by.\n\nIf not provided, the configured granularity of the information stream will be used.\n\nIf provided, it must be coarser than the information stream's granularity. Then, the data will be summed/grouped to the specified granularity.\n", "required": false, "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] } } ], "responses": { "200": { "$ref": "#/components/responses/200-2" }, "400": { "$ref": "#/components/responses/400-3" }, "401": { "$ref": "#/components/responses/401-2" }, "403": { "$ref": "#/components/responses/403-2" }, "500": { "description": "A server error. Currently also returned when the required `key` query\nparameter is omitted (a known limitation; this should be a `400`).\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred while processing the request." }, "status": { "type": "string", "example": "GENERAL_EXCEPTION" } } } } } } } } }, "/information-streams/v3/streams": { "post": { "security": [ { "apiKey": [ "forecasting" ] } ], "tags": [ "Information streams" ], "operationId": "createOrUpdateInformationStream", "summary": "Create or update an information stream", "description": "**Requires scope:** `forecasting`.\n\nCreate or update the metadata for an information stream.\n\n**Important notes:**\n\n- When updating an existing information stream, include all keys to avoid unintentionally resetting values to their defaults.\n- `departmentIds` is optional. It may contain department, department group, or location IDs. A department group or location is automatically expanded to its active child departments; the group or location ID itself is not linked. An explicitly listed department is always linked, even when archived. A non-empty selection that resolves to no active departments is rejected.\n- The linked departments are stored as a snapshot at the moment of the request. Later changes to the organizational structure (for example adding a department to a group) do not change the departments already linked to an existing information stream.\n- Department, department group, and location IDs can be looked up by fetching the department tree with [`GET /api/department-management/v3/tree`](#tag/Offices-and-departments/operation/getDepartmentTree). Fetching the department tree requires a token with the `business` scope; the `forecasting` scope alone does not grant access to it.\n- On create, `departmentIds` may be omitted; the stream is then created without linked departments.\n- On update, `departmentIds` is only applied when a non-empty list is provided. Omitting it (or sending an empty list) leaves the existing departments unchanged.\n- `granularity` is required when creating a new information stream.\n- When updating an existing information stream, `granularity` is optional. If provided, it must match the already configured granularity. Changing granularity through this endpoint is not supported.\n- When onboarding a newly realized workload information stream, ensure that all historically realized data is fully inserted.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InformationStream" } } } }, "responses": { "200": { "$ref": "#/components/responses/200-3" }, "201": { "description": "Response code 201 - CREATED", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "The Dyflexis generated information stream key" } } } } } }, "400": { "$ref": "#/components/responses/400-2" }, "401": { "$ref": "#/components/responses/401-2" }, "403": { "$ref": "#/components/responses/403-2" }, "404": { "$ref": "#/components/responses/404-2" }, "500": { "$ref": "#/components/responses/500-2" } } } }, "/information-streams/v3/datapoint/{key}": { "post": { "security": [ { "apiKey": [ "forecasting" ] } ], "tags": [ "Information streams" ], "summary": "Store data in an information stream", "description": "**Requires scope:** `forecasting`.\n\nCreate or update one or more data points for the information stream’s **base (configured) granularity** channel.\n\n**Access:** Requires an API token that includes the **`forecasting`** scope. The **forecasting** module must be enabled for the customer. Streams of any `source` can be written. A manually created (`user_provided`) stream is automatically made read-only after a successful write.\n\n**Stream shape:** The stream must be migrated to the v3 structure (configured `granularity` and matching data channel). Legacy v2-only streams respond with **400 Bad Request** (migration required).\n\n**Granularity:** If `granularity` is set on an item, it must **exactly match** the stream’s configured granularity. If omitted, that configured granularity is assumed.\n\nUnlike the deprecated timeseries upsert, this endpoint does **not** accept a **coarser** `granularity` than the stream to split across finer steps, declared granularity must match the stream.\n\n**Value `0`:** A numeric **`0`** is **stored** on the base channel for that `period` (so it is distinct from a missing point). Coarser channels are recalculated from the base channel. All values, including **0**, are applied with the same **upsert** behavior.\n\n**Rollups:** After successful writes, **coarser** granularity channels (e.g. day, week, …) are **recalculated** from the base channel where those channels exist.\n\nSuccessful requests always return **`200 OK`** with an empty body. The endpoint does not distinguish between insert and update.\n", "operationId": "storeInformationStreamData", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Information stream identifier to update the data for", "example": "covers-per-hour-pier9", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InformationStreamDataV3" } } } } }, "responses": { "200": { "$ref": "#/components/responses/200-3" }, "400": { "$ref": "#/components/responses/400-2" }, "401": { "$ref": "#/components/responses/401-2" }, "403": { "$ref": "#/components/responses/403-2" }, "404": { "$ref": "#/components/responses/404-2" }, "500": { "$ref": "#/components/responses/500-2" } } } }, "/api/setu/1.4.1/humanResource": { "post": { "security": [ { "apiKey": [ "setu" ] } ], "tags": [ "Employment agency" ], "operationId": "submitHumanResource", "summary": "Submit a human resource", "description": "**Requires scope:** `setu`.\n\nThe main element of the message, this container holds all elements needed\nto define a human resource (the person being staffed) in the SETU\nstandard. SETU is the Dutch staffing industry's XML interchange standard.\n", "requestBody": { "required": true, "content": { "application/xml": { "example": "\n \n 179943169\n \n \n \n John de Smith\n John\n John\n Smith\n \n \n \n \n 06-12345678\n \n \n 070 1234567\n \n john.doe@example.com\n \n \n \n 2516 BE\n The Hague\n \n Binckhorstlaan\n 36\n M449\n \n \n \n \n 1991-03-18\n male\n \n The Hague Office\n \n \n\n", "schema": { "type": "object", "properties": { "HumanResource": { "type": "object", "required": [ "HumanResourceId", "ResourceInformation" ], "properties": { "HumanResourceId": { "type": "object", "description": "Container for the unique identifier of the human resource.", "required": [ "idOwner", "IdValue" ], "properties": { "idOwner": { "type": "string", "description": "The organization that issues the identifier. This organization is also\nresponsible for the uniqueness of the identifier within its own context.\n", "enum": [ "StaffingCompany", "StaffingCustomer" ], "xml": { "attribute": true } }, "IdValue": { "type": "string", "description": "The unique identifier of the human resource." } } }, "ResourceInformation": { "type": "object", "description": "Information about the human resource.", "required": [ "PersonName", "EntityContactInfo" ], "properties": { "PersonName": { "type": "object", "description": "The name of the human resource.", "required": [ "FormattedName", "GivenName", "PreferredGivenName", "FamilyName" ], "properties": { "FormattedName": { "type": "string", "description": "A fully formatted name as an XML string.", "example": "Piet van der Berg" }, "GivenName": { "type": "string", "description": "The given or chosen name. The element may occur more than once,\none element for each given name.\n", "example": "Arend" }, "PreferredGivenName": { "type": "string", "description": "The preferred given name.", "example": "Piet" }, "FamilyName": { "type": "object", "description": "The family name. There can be multiple family names, but there\ncan be only one primary family name.\n", "properties": { "primary": { "type": "string", "description": "Exactly one family name is required to have `primary` set to `TRUE`.\nIndicates whether this is the primary family name or any maiden/birth\nname. Must be `TRUE` for the primary family name and `FALSE` for any\nadditional maiden/birth name.\n", "example": "TRUE", "enum": [ "TRUE", "FALSE" ], "xml": { "attribute": true } }, "prefix": { "type": "string", "description": "Prefix of the family name.", "example": "van der", "xml": { "attribute": true } } } } } }, "EntityContactInfo": { "type": "object", "description": "Contact information of the human resource.", "required": [ "ContactMethod" ], "properties": { "ContactMethod": { "type": "object", "description": "Container for information on contacting the human resource.", "required": [ "InternetEmailAddress" ], "properties": { "Mobile": { "type": "object", "description": "Container for specifying the mobile number.", "required": [ "FormattedNumber" ], "properties": { "FormattedNumber": { "type": "string", "description": "A fully formatted mobile number as an XML string." } } }, "Telephone": { "type": "object", "description": "Container for specifying the telephone number.", "required": [ "FormattedNumber" ], "properties": { "FormattedNumber": { "type": "string", "description": "A fully formatted telephone number as an XML string." } } }, "InternetEmailAddress": { "type": "string", "description": "Email address of the human resource. Will be used as the username\nfor login.\n", "example": "john.doe@example.com" } } } } }, "PostalAddress": { "type": "object", "description": "The home address of the human resource.", "properties": { "PostalCode": { "type": "string", "description": "The postal code." }, "Municipality": { "type": "string", "description": "The city." }, "DeliveryAddress": { "type": "object", "description": "Container for specifying the delivery address.", "properties": { "StreetName": { "type": "string", "description": "The street name." }, "BuildingNumber": { "type": "string", "description": "The number of the building." }, "Unit": { "type": "string", "description": "The number addition." } } } } } } }, "HumanResourceAdditionalNL": { "type": "object", "description": "Additional schema for SETU-specific elements.", "properties": { "BirthDate": { "type": "string", "description": "The birth date of the human resource in `YYYY-MM-DD` (ISO 8601).\n" }, "Sex": { "type": "string", "description": "The gender of the human resource.", "enum": [ "female", "male", "unknown" ] }, "CustomerReportingRequirements": { "type": "object", "description": "Container for (reporting) related information concerning the offer.", "properties": { "CostCenterName": { "type": "string", "description": "The name of the cost center of the staffing customer for the\nstaffing position.\n" } } } } } } } } } } } }, "responses": { "200": { "description": "Human Resource created successfully" }, "400": { "$ref": "#/components/responses/400_v3_xml" }, "401": { "$ref": "#/components/responses/401_xml" }, "403": { "$ref": "#/components/responses/403_xml" }, "503": { "$ref": "#/components/responses/503_xml" } } } }, "/api/setu/1.4.1/assignment": { "post": { "security": [ { "apiKey": [ "setu" ] } ], "tags": [ "Employment agency" ], "operationId": "submitAssignment", "summary": "Submit an assignment", "description": "**Requires scope:** `setu`.\n\nThe main element of the message, this container holds all elements needed\nto define an assignment (a human resource placed at a staffing customer) in\nthe SETU standard.\n", "requestBody": { "required": true, "content": { "application/xml": { "example": "\n \n 1234/1234561\n \n \n \n 223445\n \n \n 179943169\n \n \n 23456\n \n \n \n \n \n \n The Hague Office\n \n \n 16.00\n TimeInterval\n 100\n 2026-02-01\n \n \n \n \n \n 32\n \n \n 2026-02-01\n 2026-08-01\n 2026-08-01\n \n \n \n 1.4\n Lasser\n true\n \n \n\n", "schema": { "type": "object", "properties": { "Assignment": { "type": "object", "required": [ "assignmentStatus", "AssignmentId", "ReferenceInformation", "CustomerReportingRequirements", "Rates", "StaffingShift", "AssignmentDateRange", "UserArea" ], "properties": { "assignmentStatus": { "type": "string", "description": "Specifies the intended action of the Assignment message.\nCurrently only `active` is supported.\n", "enum": [ "active", "cancelled", "revised", "x:rejected" ], "xml": { "attribute": true } }, "AssignmentId": { "type": "object", "description": "Container for the unique identifier of the assignment.", "required": [ "idOwner", "IdValue" ], "properties": { "idOwner": { "type": "string", "description": "The organization that issues the identifier. Also responsible for the\nuniqueness of the identifier within its own context.\n", "enum": [ "StaffingCompany" ] }, "IdValue": { "type": "string", "description": "The unique identifier of the assignment." } } }, "ReferenceInformation": { "type": "object", "description": "Container for references to the staffing customer and the human resource.\n", "required": [ "StaffingCustomerId", "HumanResourceId", "PositionId" ], "properties": { "StaffingCustomerId": { "type": "object", "description": "Container for the identifier of the staffing customer.", "required": [ "idOwner", "IdValue" ], "properties": { "idOwner": { "type": "string", "description": "The organization that issues the identifier. Also responsible for\nuniqueness of the identifier within its own context.\n", "enum": [ "BTW", "Fi", "KvK", "OIN", "StaffingCompany", "StaffingCustomer" ] }, "IdValue": { "type": "string", "description": "The unique identifier of the staffing customer." } } }, "HumanResourceId": { "type": "object", "description": "Container for the reference to the human resource. May appear multiple\ntimes.\n", "required": [ "idOwner", "IdValue" ], "properties": { "idOwner": { "type": "string", "description": "The organization that issues the identifier. Also responsible for\nuniqueness of the identifier within its own context.\n", "enum": [ "StaffingCompany", "StaffingCustomer" ], "xml": { "attribute": true } }, "IdValue": { "type": "string", "description": "The unique identifier of the human resource." } } }, "PositionId": { "type": "object", "description": "Not used in SETU, but mandatory in HR-XML.", "required": [ "IdValue" ], "properties": { "IdValue": { "type": "string", "description": "Not used in SETU, but mandatory in HR-XML. Must be included on\nthe message but left empty.\n" } } } } }, "CustomerReportingRequirements": { "type": "object", "description": "Container for (reporting) related information concerning the offer.", "properties": { "CostCenterName": { "type": "string", "description": "The name of the cost center of the staffing customer for the\nstaffing position.\n" } } }, "Rates": { "type": "object", "description": "Information about the rates for the assignment. May appear multiple times.\n", "required": [ "rateType", "rateStatus", "Amount", "Class", "StartDate" ], "properties": { "rateType": { "type": "string", "description": "Whether the rate should be billed to the staffing customer or paid to\nthe human resource.\n", "enum": [ "bill", "pay" ], "xml": { "attribute": true } }, "rateStatus": { "type": "string", "description": "The `rates` container is used in multiple standards. In the Assignment\nmessage `rateStatus` must always be `agreed`. Agreement on the rate is\ndone in a framework agreement or during ordering and selection.\n", "enum": [ "agreed" ], "xml": { "attribute": true } }, "Amount": { "type": "object", "description": "The amount of the rate.", "required": [ "rateAmountPeriod", "currency" ], "properties": { "rateAmountPeriod": { "type": "string", "description": "The timeframe the rate applies to. Also used to indicate whether a\nmark-up is consolidated within the rate or specified as a separate\n(split) rate.\n", "enum": [ "hourly" ], "xml": { "attribute": true } }, "currency": { "type": "string", "description": "The currency in which the rate amount is specified.", "enum": [ "EUR" ], "xml": { "attribute": true } } } }, "Class": { "type": "string", "description": "Whether the rate applies to an allowance, an expense, or a time interval.\n", "enum": [ "Allowance", "Expense", "TimeInterval" ] }, "Multiplier": { "type": "string", "description": "Mandatory for rates with `Class` set to `TimeInterval`, optional for\nother rate types.\n" }, "StartDate": { "type": "string", "description": "The date from which the rate applies. `YYYY-MM-DD` (ISO 8601).\n" } } }, "StaffingShift": { "type": "object", "description": "Container specifying the number of hours a human resource is hired for.\nMay appear multiple times.\n", "required": [ "Id" ], "properties": { "shiftPeriod": { "type": "string", "description": "Unused in Dyflexis but may be included in the request.", "xml": { "attribute": true } }, "Id": { "type": "object", "description": "Not used in SETU, but mandatory in HR-XML.", "required": [ "IdValue" ], "properties": { "IdValue": { "description": "Not used in SETU, but mandatory in HR-XML, must be empty." } } }, "Hours": { "type": "number", "description": "Unused in Dyflexis but may be included in the request." } } }, "AssignmentDateRange": { "type": "object", "description": "The start and expected end date of the assignment.", "required": [ "StartDate" ], "properties": { "StartDate": { "type": "string", "description": "The start date of the assignment. `YYYY-MM-DD` (ISO 8601).\n" }, "ExpectedEndDate": { "type": "string", "description": "The expected end date of the assignment. Provided if known.\nExpiration of this date does not mean that the assignment has ended.\n`YYYY-MM-DD` (ISO 8601).\n" }, "ActualEndDate": { "type": "string", "description": "The actual end date of the assignment. Related time cards containing\nworking hours dated after this `ActualEndDate` cannot be processed.\n`YYYY-MM-DD` (ISO 8601).\n" } } }, "UserArea": { "type": "object", "description": "Container for references to the `UserArea`.", "required": [ "AssignmentAdditionalNL" ], "properties": { "AssignmentAdditionalNL": { "type": "object", "required": [ "SETUVersionId" ], "properties": { "SETUVersionId": { "type": "string", "description": "Version of the SETU standard used for `Assignment`.", "enum": [ "1.4" ] }, "JobTitle": { "type": "string", "description": "The title of the position the human resource will fulfil.\n" }, "InclusiveRate": { "type": "boolean", "description": "Unused in Dyflexis but may be included in the request." } } } } } } } } } } } }, "responses": { "200": { "description": "Assignment sent successfully" }, "400": { "$ref": "#/components/responses/400_v3_xml" }, "401": { "$ref": "#/components/responses/401_xml" }, "403": { "$ref": "#/components/responses/403_xml" }, "503": { "$ref": "#/components/responses/503_xml" } } } } }, "webhooks": { "payrollPeriodReady": { "post": { "tags": [ "Payroll" ], "security": [], "operationId": "payrollPeriodReadyEvent", "summary": "Payroll period ready", "description": "> **Webhook**, Dyflexis sends this `POST` request to a URL **you** host. See the [Webhooks guide](/guides/webhooks) for how to register your receiver and what it must return.\n\nSends a message when the payroll data is ready. You can use the\npayload to call a desired endpoint.\n\nThe webhook can't be registered with this API. Please register\nthis webhook in Dyflexis.\n", "requestBody": { "description": "Sends a message when the payroll data is ready. You can use the payload to call a desired endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPayroll" } } } }, "responses": { "200": { "$ref": "#/components/responses/200-3" }, "503": { "$ref": "#/components/responses/503" } } } }, "sickLeaveRegistration": { "post": { "tags": [ "Absence" ], "security": [], "operationId": "sickLeaveRegistrationEvent", "summary": "Sick leave registration event", "description": "> **Webhook**, Dyflexis sends this `POST` request to a URL **you** host. See the [Webhooks guide](/guides/webhooks) for how to register your receiver and what it must return.\n\nSends a message when a sick leave registration is created or\nrecovered. Use the envelope field `type` to determine which\nevent you received:\n\n- `sick_leave_created`, a new sick-leave registration has been\n filed.\n- `sick_leave_recovered`, an existing registration has been\n closed because the employee recovered.\n\nThe webhook can't be registered with this API. Please register\nthis webhook in Dyflexis.\n", "requestBody": { "description": "Sends a message when a sick leave registration is created or recovered. Use the envelope field `type` to determine which event you received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SickLeaveRegistrationWebhookEnvelope" } } } }, "responses": { "200": { "$ref": "#/components/responses/200-3" }, "503": { "$ref": "#/components/responses/503" } } } }, "timeCard": { "post": { "security": [], "tags": [ "Employment agency" ], "operationId": "timeCardEvent", "summary": "Time card event", "description": "> **Webhook**, Dyflexis sends this `POST` request to a URL **you** host. See the [Webhooks guide](/guides/webhooks) for how to register your receiver and what it must return.\n\nThe main element of the message, this container holds all elements\nneeded to define a time card (the reported hours, allowances and\nexpenses of a human resource for a period).\n\nThe webhook can't be registered with this API. Please register\nthis webhook in Dyflexis.\n", "requestBody": { "description": "The time card payload (reported hours, allowances and expenses of a\nhuman resource for a period). Dyflexis POSTs this body to the URL\nyou host.\n", "required": true, "content": { "application/xml": { "example": "\n \n 1234567890\n \n \n \n \n 23456\n \n \n John de Smith\n Piet\n Smith\n \n \n \n \n 2026-12-31\n 2026-12-31\n \n \n 1234567890\n \n 2026-12-31\n 2026-12-31\n 30\n \n \n \n TC00123456-4\n \n 14.00\n 2\n \n \n \n Dyflexis\n 2026-11-02T06:30:00+1:00\n \n \n 2026-11-01T09:31:14+1:00\n \n \n \n \n true\n \n \n \n 223445\n \n \n 1234/1234561\n \n \n \n \n\n", "schema": { "type": "object", "properties": { "TimeCard": { "type": "object", "properties": { "Id": { "type": "object", "description": "Container for the unique identifier of the time card.", "properties": { "idOwner": { "type": "string", "enum": [ "StaffingCustomer" ], "xml": { "attribute": true } }, "IdValue": { "type": "string", "description": "The unique identifier of the time card." } } }, "ReportedResource": { "type": "object", "description": "Information on the human resource conducting the activities,\nincluding a limited amount of details and an optional reference to a\nrecord with a more detailed description.\n", "properties": { "Person": { "type": "object", "description": "The human resource for whom time, allowances and/or expenses\nare reported.\n", "properties": { "Id": { "type": "object", "description": "Reference to a human resource.", "properties": { "idOwner": { "type": "string", "description": "The organization that issues the identifier. Also responsible\nfor uniqueness within its own context.\n", "enum": [ "StaffingCompany", "StaffingCustomer" ], "xml": { "attribute": true } }, "IdValue": { "type": "string", "description": "The unique identifier of the human resource." } } }, "PersonName": { "type": "object", "description": "The name of the human resource.", "properties": { "FormattedName": { "type": "string", "description": "A fully formatted name as an XML string." }, "PreferredGivenName": { "type": "string", "description": "The preferred given name." }, "FamilyName": { "type": "object", "description": "The family name.", "properties": { "primary": { "type": "string", "description": "Exactly one family name is required to have `primary` set\nto `TRUE`. Indicates whether this is the primary family\nname or any maiden/birth name.\n", "example": "TRUE", "enum": [ "TRUE", "FALSE" ], "xml": { "attribute": true } }, "prefix": { "type": "string", "description": "Prefix of the family name.", "example": "van der", "xml": { "attribute": true } } } } } } } } } }, "ReportedTime": { "type": "object", "description": "Container for information about the reported working hours, allowances\nand expenses of the human resource for a certain period of time.\n", "properties": { "status": { "type": "string", "description": "The status of the time card in the process. `approved` is conveyed\nas an empty value; `declined` is conveyed as `rejected`.\n", "enum": [ "", "rejected" ], "xml": { "attribute": true } }, "PeriodStartDate": { "type": "string", "description": "The start date and/or time of the timeframe reported on the time\ncard. `YYYY-MM-DDThh:mm:ssZ` (ISO 8601); if no timezone is provided\nDyflexis system time is used.\n" }, "PeriodEndDate": { "type": "string", "description": "The end date and/or time of the timeframe reported on the time\ncard. `YYYY-MM-DDThh:mm:ssZ` (ISO 8601); if no timezone is provided\nDyflexis system time is used.\n" }, "TimeInterval": { "type": "object", "description": "Container for information about the reported working hours of the\nhuman resource. May appear multiple times.\n", "properties": { "type": { "type": "string", "description": "The type of time frame registered, using the SETU hour-types\ncode list.\n", "xml": { "attribute": true } }, "Id": { "type": "object", "description": "Container for a unique identifier of the reported time interval.\n", "properties": { "idOwner": { "type": "string", "description": "The organization that issues the identifier. Also responsible\nfor uniqueness within its own context.\n", "enum": [ "StaffingCompany", "StaffingCustomer" ], "xml": { "attribute": true } }, "IdValue": { "type": "string", "description": "The unique identifier of the time interval." } } }, "StartTimeDate": { "type": "string", "description": "The start date and time of the reported time interval.\n`YYYY-MM-DDThh:mm:ssZ` (ISO 8601).\n" }, "EndTimeDate": { "type": "string", "description": "The end date and time of the reported time interval.\n`YYYY-MM-DDThh:mm:ssZ` (ISO 8601).\n" }, "RateOrAmount": { "type": "object", "description": "Specification of the (agreed) rate that applies to the reported\ntime interval. May appear multiple times.\n", "properties": { "currency": { "type": "string", "description": "The currency in which the rate or amount is specified. Only\nEuro (`EUR`) is supported.\n", "enum": [ "EUR" ], "xml": { "attribute": true } }, "type": { "type": "string", "description": "Type of rate that applies to the activities conducted.\n", "enum": [ "4weekly", "hourly", "hourlyconsolidated", "hourlysplit", "monthly", "weekly" ], "xml": { "attribute": true } }, "multiplier": { "type": "number", "format": "float", "description": "The multiplier to apply to the rate to determine the real\namount paid or billed. `100` (the \"standard multiplier\")\nrepresents 100% (no mark-up). A 50% mark-up, 1.5× the\nstandard rate, is represented as `150`.\n", "xml": { "attribute": true } } } } } }, "Allowance": { "type": "object", "description": "Specification of expenses (costs incurred representing eligibility)\nand/or allowances (additional bonuses given for the duration of\nthe represented time interval) for a specific time period. May\nappear multiple times.\n", "properties": { "type": { "type": "string", "description": "The type of expense or allowance reported, using the SETU\nexpense-allowance-types code list.\n", "xml": { "attribute": true } }, "Id": { "type": "object", "description": "Identifier of the reported allowance or expense.", "properties": { "idOwner": { "type": "string", "description": "The organization that issues the identifier. Also responsible\nfor uniqueness within its own context.\n", "enum": [ "StaffingCompany", "StaffingCustomer" ], "xml": { "attribute": true } }, "IdValue": { "type": "object", "description": "The unique identifier of the allowance.", "properties": { "name": { "type": "string", "description": "Specifies whether the item is an expense or an allowance.\n", "enum": [ "allowance", "expense" ], "xml": { "attribute": true } } } } } }, "Amount": { "type": "object", "description": "The amount per unit of the allowance or expense.\n", "properties": { "currency": { "type": "string", "description": "The currency of the specified amount.", "enum": [ "EUR" ], "xml": { "attribute": true } } } }, "Quantity": { "type": "integer", "description": "Numerical quantity of the expense or allowance, assigned or\ndetermined by calculation or measurement. Cannot be negative.\n" } } } } }, "SubmitterInfo": { "type": "object", "description": "Who (person or system) submitted the time card to the staffing supplier\nand when.\n", "properties": { "Source": { "type": "string", "description": "The person or system that submitted the time card. Always\n`Dyflexis`.\n" }, "SubmittedDateTime": { "type": "string", "description": "Timestamp of when the time card was submitted.\n`YYYY-MM-DDThh:mm:ssZ` (ISO 8601).\n" } } }, "ApprovalInfo": { "type": "object", "description": "Who approved (or rejected) the time card and when.\n", "properties": { "ApprovedDateTime": { "type": "string", "description": "Timestamp of when the time card was approved, or rejected (for\na rejected time card). `YYYY-MM-DDThh:mm:ssZ` (ISO 8601).\n" } } }, "AdditionalData": { "type": "object", "description": "Container for specifying additional elements.", "properties": { "StaffingAdditionalData": { "type": "object", "description": "Container for additional reporting and reference elements.\n", "properties": { "CustomerReportingRequirements": { "type": "object", "description": "Container for a variety of customer-related reporting elements.\n", "properties": { "AdditionalRequirement": { "type": "object", "description": "Any other customer-specific reporting requirement needed.\n", "properties": { "requirementTitle": { "type": "string", "description": "The name of the additional reporting requirement, using\nthe SETU time-card customer-specific-requirements code\nlist.\n", "xml": { "attribute": true } } } } } }, "ReferenceInformation": { "type": "object", "description": "References to other documents or parties.", "properties": { "StaffingCustomerId": { "type": "object", "description": "Container for the unique identifier of the staffing customer.\n", "properties": { "idOwner": { "type": "string", "description": "The organization that issues the identifier. Also\nresponsible for uniqueness within its own context.\n", "enum": [ "BTW", "Fi", "KvK", "OIN", "StaffingCompany", "StaffingCustomer" ], "xml": { "attribute": true } }, "IdValue": { "type": "string", "description": "The unique identifier of the staffing customer." } } }, "AssignmentId": { "type": "object", "description": "Container for the unique identifier of the assignment.\n", "properties": { "idOwner": { "type": "string", "enum": [ "StaffingCompany" ], "xml": { "attribute": true } }, "IdValue": { "type": "string", "description": "The unique identifier of the assignment." } } } } } } } } } } } } } } } }, "responses": { "200": { "description": "Time card received successfully." }, "400": { "$ref": "#/components/responses/400_v3_xml" }, "401": { "$ref": "#/components/responses/401_xml" }, "403": { "$ref": "#/components/responses/403_xml" }, "503": { "$ref": "#/components/responses/503_xml" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "x-displayName": "API key", "description": "**Required.** Authenticate with the API key issued to you by Dyflexis.\n\nThe wire format is:\n\n```\nAuthorization: Token YOUR_AUTH_TOKEN\n```\n\nIn the Try-it console, the **Security** tab comes pre-filled:\n**Name** contains `Authorization` and **API key** contains\n`Token YOUR_AUTH_TOKEN`. Replace `YOUR_AUTH_TOKEN` with your\nAPI key, keeping the `Token ` prefix.\n\nAPI keys are scoped to permissions (`payroll`, `clock`,\n`business`, `absence`, `external_employees`, `employee_data`,\n`employee_mappings`, `attendance_registration`,\n`information_lines`, `payroll_hours`, `forecasting`, `setu`);\nthe required scope is shown on each operation." }, "XDyflexisAuthToken": { "type": "apiKey", "in": "header", "name": "X-Dyflexis-AuthToken", "x-displayName": "Legacy v0 token", "description": "Legacy authentication for the `v0` endpoints only: send the API\nkey issued to you by Dyflexis in the `X-Dyflexis-AuthToken`\nheader, without a prefix. Every other endpoint authenticates\nwith the `Authorization: Token ...` header instead." } }, "schemas": { "ClockEvent": { "type": "string", "description": "Either \"clocked in\" or \"clocked out\"", "example": "clocked in", "enum": [ "clocked in", "clocked out" ] }, "Contracts": { "type": "array", "minItems": 1, "description": "An array of at least one or more contracts", "items": { "$ref": "#/components/schemas/Contract" } }, "Contract": { "type": "object", "properties": { "contractReference": { "type": "string", "description": "Unique reference to the contract per employee. This could be a serial number or a unique id provided by an external system." }, "office": { "type": "integer", "description": "Identifier of the Dyflexis office.", "example": 1 }, "type": { "type": "integer", "description": "Identifier of the Dyflexis contract type", "example": 1 }, "start": { "type": "string", "example": "2026-01-01", "description": "Startdate of contract in YYYY-MM-DD format" }, "end": { "example": "2026-12-31", "type": "string", "description": "Enddate of contract in YYYY-MM-DD format" }, "hours": { "type": "number", "description": "Contractual hours the employee works in a workweek.", "example": 40 }, "days": { "type": "number", "description": "Average days the employee works in a workweek.", "example": 5 }, "salary": { "type": "number", "description": "Remuneration for employment per hour.", "example": 12.95 }, "maxHoursPerWeek": { "type": [ "number", "null" ], "description": "Max hours the employee works in a workweek (only synchronised when the \"upper limit\" setting is enabled for the contract type).", "example": 50 } } }, "HourStatus": { "type": "string", "description": "Whether the registered hour has been approved, declined, or registered", "enum": [ "approved", "declined", "registered" ] }, "SendPayroll": { "properties": { "queueId": { "type": "integer", "description": "Unique queue id.", "example": 97 }, "systemName": { "type": "string", "description": "Name of the system.", "example": "organisation-a" }, "officeId": { "type": "integer", "description": "Unique identifier of the office.", "example": 1 }, "officeName": { "type": "string", "description": "Name of the office.", "example": "department-b" }, "contractTypeGroupName": { "type": "string", "description": "contract type.", "example": "fixed" }, "periodLabel": { "type": "string", "description": "The payroll period label. A combination of year followed by the period identifier as configured for your system.", "example": "2026-M03" }, "targetPeriod": { "type": "string", "description": "The period (e.g. a month or a week).", "example": "03" }, "targetYear": { "type": "string", "description": "The year.", "example": "2026" } } }, "SickLeaveRegistrationWebhookEnvelope": { "type": "object", "properties": { "type": { "type": "string", "description": "Webhook event type.", "example": "sick_leave_created", "enum": [ "sick_leave_created", "sick_leave_recovered" ] }, "timestamp": { "type": "string", "description": "Event timestamp in ISO 8601 UTC.", "example": "2026-02-25T14:20:35Z" }, "payload": { "$ref": "#/components/schemas/SickLeaveRegistrationWebhookPayload" } }, "required": [ "type", "timestamp", "payload" ] }, "SickLeaveRegistrationWebhookPayload": { "type": "object", "required": [ "id", "employeeId", "employeeReference", "personnelNumber", "startDate", "expectedEndDate", "endDate", "remark", "recovered", "sickDays" ], "properties": { "id": { "type": "string", "description": "The id of the sick leave registration.", "example": "01GYS27FFVTP63WGPV34V1WR6P" }, "employeeId": { "type": "integer", "description": "The id of the employee.", "example": 12 }, "employeeReference": { "type": [ "string", "null" ], "description": "External employee reference used by payroll/customer APIs, or null if not available.", "example": "EMP-EXT-123" }, "personnelNumber": { "type": [ "string", "null" ], "description": "The personnel number of the employee or null if no personnel number exists.", "example": "23V600" }, "startDate": { "$ref": "#/components/schemas/Date", "description": "Start date of sick leave in ISO 8601." }, "expectedEndDate": { "$ref": "#/components/schemas/Date", "description": "The expected end date of sick leave in ISO 8601." }, "endDate": { "type": [ "string", "null" ], "description": "The actual registered end date of sick leave in ISO 8601, or null if no end date has been specified.", "example": "2026-12-31" }, "remark": { "type": [ "string", "null" ], "description": "The remark of the sick leave registration, or null if none was given.", "example": "sore throat" }, "recovered": { "type": "boolean", "description": "Indicates whether the employee is recovered.", "example": false }, "sickDays": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the sick leave registration day.", "example": "01GYS27FFVTP63WGPV34V1WR6P" }, "date": { "$ref": "#/components/schemas/Date", "description": "The date of the sick day in ISO 8601." }, "hourType": { "type": "string", "description": "The specified hour type for that day.", "example": "standard sick leave" } } } } } }, "InformationStreamTimeseries": { "description": "Request body for the deprecated PUT /api/timeseries/v3/create endpoint. Uses `departments` (array of integers).", "type": "object", "required": [ "category", "granularity", "name", "type", "unit", "departments", "sourceSystem", "sourceSystemSupportEmail" ], "properties": { "key": { "type": "string", "description": "The key of the existing information stream. If no key is provided, Dyflexis will generate and return the key.", "example": "covers-per-hour-pier9" }, "type": { "type": "string", "description": "Type of the information stream.", "example": "workload", "enum": [ "workload", "employee_capacity" ] }, "unit": { "type": "string", "description": "Unit of the information stream. If type is \"workload\" any string is allowed. If type is \"employee_capacity\" only 'hours' or 'currency' are allowed.\n", "example": "covers" }, "category": { "type": "string", "description": "Category of the information stream", "example": "realized", "enum": [ "budget", "forecast", "realized" ] }, "granularity": { "type": "string", "description": "Granularity of the information stream.", "example": "hour", "enum": [ "minute", "hour", "day", "week", "month", "quarter", "year" ] }, "name": { "type": "string", "description": "Name of the information stream. Visible for users in Dyflexis.", "example": "Pier 9 covers per hour" }, "note": { "type": "string", "example": "Realised covers per hour at the Pier 9 Bistro, used to drive demand-based scheduling.", "description": "Additional notes about the information stream." }, "departments": { "type": "array", "description": "List of department IDs (integers) linked to the information stream. Required for the deprecated timeseries API.\nTo know which departments are available, use the List Offices endpoint or configure in the forecasting module in Dyflexis.\n", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] }, "attributes": { "type": "object", "description": "Additional attributes for the information stream.", "example": { "onlyFreeWalkIn": true } }, "isActive": { "type": "boolean", "description": "Indicates whether the information stream is visible for operations.", "example": true }, "sourceSystem": { "type": "string", "description": "Source system of the 3rd party tech provider.", "example": "Hospitality POS solutions" }, "sourceSystemSupportEmail": { "type": "string", "description": "Support email address of the tech partner.", "example": "techsupport@techpartner.com" } } }, "InformationStream": { "type": "object", "required": [ "category", "name", "type", "isActive", "sourceSystem", "sourceSystemSupportEmail" ], "properties": { "key": { "type": "string", "description": "The key of the existing information stream.\nIf no key parameter is given, Dyflexis will create a new information stream and return the generated stream key.\nOnly information streams with source `api` can be updated through this endpoint.\n", "example": "covers-per-hour-pier9" }, "type": { "type": "string", "description": "Type of the information stream.", "example": "workload", "enum": [ "workload", "staff" ] }, "unit": { "type": "string", "description": "Unit of the information stream\nIf type is \"workload\": any string value is allowed. String value 'revenue' will automatically display the currency icon in Dyflexis.\nIf type is \"staff\": only types 'hours' or 'currency' are allowed.\n", "example": "covers" }, "category": { "type": "string", "description": "Category of the information stream", "example": "realized", "enum": [ "budget", "forecast", "realized" ] }, "granularity": { "type": "string", "description": "Granularity of the information stream.\nRequired when creating a new information stream.\nOptional when updating an existing information stream. If provided on update, it must match the existing granularity.\nChanging granularity through this endpoint is not supported.\n", "example": "hour", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] }, "name": { "type": "string", "description": "Name of the information stream. Visible for users in Dyflexis.", "example": "Pier 9 covers per hour" }, "note": { "type": "string", "example": "Realised covers per hour at the Pier 9 Bistro, used to drive demand-based scheduling.", "description": "Additional notes about the information stream." }, "departmentIds": { "type": "array", "description": "List of department, department group, or location IDs linked to the information stream. Optional.\nA department group or location is automatically expanded to its active child departments; the group or location ID itself is not linked. An explicitly listed department is always linked, even when archived. A non-empty selection that resolves to no active departments is rejected.\nThe linked departments are stored as a snapshot at the moment of the request; later changes to the organizational structure do not change the departments already linked to an existing information stream.\nOn create, may be omitted to create a stream without linked departments.\nOn update, only applied when a non-empty list is provided; omitting it (or sending an empty list) leaves the existing departments unchanged.\nDepartment, department group, and location IDs can be looked up by fetching the department tree with [`GET /api/department-management/v3/tree`](#tag/Offices-and-departments/operation/getDepartmentTree); this requires a token with the `business` scope.\nCan also be configured manually in the frontend of the forecasting module in Dyflexis.\n", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] }, "isActive": { "type": "boolean", "description": "Indicates whether the information stream is visible for operations or not (if 'true', it will be visible for the performance dashboard, reporting, scheduling).", "example": true }, "sourceSystem": { "type": "string", "description": "Source system of the 3rd party tech provider.", "example": "Hospitality POS solutions" }, "sourceSystemSupportEmail": { "type": "string", "description": "Support email address of the tech partner.", "example": "techsupport@techpartner.com" } } }, "InformationStreamData": { "type": "object", "required": [ "period", "value" ], "properties": { "granularity": { "type": "string", "description": "Granularity of the information stream object.\n\nWhen data is inserted, it needs to match the granularity of the information stream or be of coarser granularity. For example, if the information stream has a granularity of 'hour', the granularity of the data sent cannot be 'minute' (finer granularity). Optionally the coarser data can be made finer by dividing it according to a default trend (see trends endpoint below).\n", "example": "hour", "enum": [ "minute", "hour", "day", "week", "month", "quarter", "year" ] }, "period": { "type": "string", "example": "2026-04-02 11:05:00", "description": "Timeframe period covered by the inserted data.\n\nAllowed values (by granularity):\n- minute (e.g. `2026-04-02 11:05:00`)\n- hour (e.g. `2026-04-02 11:05:00`)\n- day (e.g. `2026-04-02`)\n- week (e.g. `2026-W09`)\n- month (e.g. `2026-M05`)\n- quarter (e.g. `2026-Q02`)\n- year (e.g. `2026`)\n\nNotes:\n- Seconds in timestamps are ignored. Only one data point per minute is allowed (if two points have the same minute, the latter will overwrite the former).\n- The `period` should specify the lower bound of the time window, where the window is `granularity` long. For example, if `granularity=\"hour\"`, the value at `period=\"2026-04-02 11:00:00\"` should indicate the value between \"2026-04-02 11:00:00\" and \"2026-04-02 12:00:00\".\n" }, "value": { "description": "Numeric value of the information stream data record.", "example": 25, "oneOf": [ { "type": "number" }, { "type": "string", "description": "Numeric strings are also accepted by current backend validation." } ] }, "lowerBound": { "type": "number", "description": "Lower bound of value. Only available if category is 'forecast'.", "example": 20 }, "upperBound": { "type": "number", "description": "Upper bound of value. Only available if category is 'forecast'.", "example": 28 } } }, "InformationStreamDataV3": { "description": "Request body item for `POST /information-streams/v3/datapoint/{key}`.\n\n**Differences from `InformationStreamData` (deprecated timeseries upsert):** If `granularity` is sent, it must **exactly match** the stream’s configured granularity, the deprecated API still allowed **coarser** payloads to be split across finer periods.\n", "type": "object", "required": [ "period", "value" ], "properties": { "granularity": { "type": "string", "description": "Optional. When set, must **exactly equal** the information stream’s configured granularity (otherwise **400**).\n\nIf omitted, the stream’s configured granularity is used.\n", "example": "hour", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] }, "period": { "type": "string", "example": "2026-04-02 11:00:00", "description": "Timeframe for the data point, aligned to the stream’s granularity (see `granularity`).\n\nFormats (by configured stream granularity):\n- **hour**, `yyyy-mm-dd hh:mm:ss` (time is normalized to the start of the hour; seconds are not significant beyond that)\n- **day**, `yyyy-mm-dd`\n- **week**, `yyyy-Www` (ISO week, e.g. `2026-W09`)\n- **month**, `yyyy-Mmm` (e.g. `2026-M05`)\n- **quarter**, `yyyy-Qq` (e.g. `2026-Q2`)\n- **year**, `yyyy`\n\nThe period denotes the **start** of the bucket (lower bound of the interval covered by that granularity).\n" }, "value": { "description": "Numeric value for the data point, including **`0`**, which is **stored** as a real value for this `period` (distinct from a point that was never sent).\n", "example": 25, "oneOf": [ { "type": "number" }, { "type": "string", "description": "Numeric strings are also accepted by current backend validation." } ] }, "lowerBound": { "type": "number", "description": "Lower bound of value.", "example": 20 }, "upperBound": { "type": "number", "description": "Upper bound of value.", "example": 28 } } }, "WorkingPattern": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date", "description": "Start date of the working pattern", "example": "2026-12-01" }, "startWeek": { "type": "integer", "description": "The week of the working pattern cycle that is used on the start date. Start week may not be greater than the number of weeks", "example": 1 }, "weeks": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Working pattern weeks", "items": { "$ref": "#/components/schemas/Week" } } } }, "Week": { "type": "object", "properties": { "monday": { "$ref": "#/components/schemas/NumericDay" }, "tuesday": { "$ref": "#/components/schemas/NumericDay" }, "wednesday": { "$ref": "#/components/schemas/NumericDay" }, "thursday": { "$ref": "#/components/schemas/NumericDay" }, "friday": { "$ref": "#/components/schemas/NumericDay" }, "saturday": { "$ref": "#/components/schemas/NumericDay" }, "sunday": { "$ref": "#/components/schemas/NumericDay" } } }, "NumericDay": { "type": "object", "properties": { "contractHours": { "type": "number", "format": "float", "description": "Number of contract hours", "example": 8 } } }, "NameFormat": { "description": "Defines how the employee name should be displayed in Dyflexis", "oneOf": [ { "type": "string", "enum": [ "mine", "partner", "mine-partner", "partner-mine" ] } ] }, "MaritalStatus": { "type": "string", "description": "Whether the employee is single, married, living together or permanently separated", "oneOf": [ { "type": "string", "enum": [ "single", "married", "living-together", "permanently-separated", "registered-partnership", "widowed" ] } ] }, "Gender": { "type": "string", "oneOf": [ { "type": "string", "enum": [ "male", "female" ] } ] }, "Date": { "type": "string", "example": "2026-12-31" }, "ApiError": { "type": "object", "description": "Standard JSON error body, returned only when the request sends an\n`Accept: application/json` header (otherwise an HTML error page may be\nreturned). `title`, `status`, and `message` are always present. `detail`\nand `code` are returned by some backend versions and may be absent.\n", "required": [ "title", "status", "message" ], "properties": { "title": { "type": "string", "description": "Short, human-readable summary of the error.", "example": "Unauthorized" }, "status": { "type": "integer", "description": "The HTTP status code.", "example": 401 }, "message": { "type": "string", "description": "Human-readable explanation of this occurrence of the error.", "example": "Invalid Token" }, "detail": { "type": "string", "description": "Human-readable explanation of this occurrence. Not returned by all backend versions.", "example": "Invalid Token" }, "code": { "type": "integer", "description": "The HTTP status code (duplicate of `status`). Not returned by all backend versions.", "example": 401 } } }, "Email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "UTC_DateTimeOrNull": { "type": [ "string", "null" ], "example": "2026-01-01T00:00:00Z", "description": "DateTime in UTC ISO 8601 format" }, "Department": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string" }, "type": { "type": "string", "description": "Defines the type of organizational unit", "example": "department", "enum": [ "office", "department_group", "department" ] }, "created": { "$ref": "#/components/schemas/UTC_DateTimeOrNull" }, "modified": { "$ref": "#/components/schemas/UTC_DateTimeOrNull" }, "costCenterId": { "type": [ "string", "null" ], "example": "123" }, "active": { "type": "boolean", "description": "Indicates whether the department is currently active", "example": true } } }, "UTC_DateTime": { "type": "string", "example": "2026-01-01T00:00:00Z", "description": "DateTime in UTC ISO 8601 format" }, "ValidationError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "type": "object", "description": "Returned when request validation fails. In addition to the base error\nfields, validation failures carry per-field detail. The exact structure\ndepends on the backend version: some versions return a `violations`\narray, others a `violationList` object together with an `errors` array.\nRead whichever is present.\n", "properties": { "type": { "type": "string", "description": "URI reference identifying the error type, when present.", "example": "https://tools.ietf.org/html/rfc2616#section-10" }, "violations": { "type": "array", "description": "Per-field validation failures (one backend variant).", "items": { "type": "object", "properties": { "propertyPath": { "type": "string", "example": "employeeId" }, "title": { "type": "string", "example": "This value should not be null." }, "type": { "type": [ "string", "null" ] } } } }, "violationList": { "type": "object", "description": "Per-field validation failures keyed by field name (another backend variant).", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "errors": { "type": "array", "description": "Per-field validation failures (another backend variant).", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "This value should not be null." }, "code": { "type": [ "string", "null" ], "description": "Machine-readable violation code." }, "context": { "type": "object", "properties": { "field": { "type": [ "string", "null" ] } } } } } } } } ] }, "DateTime": { "type": "string", "example": "2026-12-31T12:34:56+01:00", "description": "DateTime in ISO 8601 format" }, "PayrollStatus": { "description": "The new status for the queue item", "oneOf": [ { "type": "string", "description": "One of \"in progress\", \"success\", \"failed\", \"partial\"", "enum": [ "in progress", "success", "failed", "partial" ] } ] }, "Ulid": { "type": "string", "description": "A ULID (Universally Unique Lexicographically Sortable Identifier): 26 characters of Crockford base32.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "example": "01GYS27FFVTP63WGPV34V1WR6P" }, "InformationStreamListItem": { "type": "object", "properties": { "key": { "type": "string", "description": "Identifier of the information stream", "example": "bar-revenue-pier9" }, "isActive": { "type": "boolean", "description": "Indicates if the information stream is active", "example": true }, "source": { "type": "string", "description": "Source of the information stream", "example": "user_provided" }, "type": { "type": "string", "description": "Type of the information stream", "example": "revenue" }, "granularity": { "type": "string", "description": "Granularity of the information stream", "example": "day" }, "category": { "type": "string", "description": "Category of the information stream", "example": "realized" }, "departments": { "type": "array", "items": { "type": "integer" }, "description": "List of departments IDs associated with the information stream", "example": [ 1, 2 ] }, "unit": { "type": "string", "description": "Unit of the information stream", "example": "currency" }, "name": { "type": "string", "description": "Name of the information stream", "example": "Pier 9 bar revenue" }, "note": { "type": [ "string", "null" ], "description": "Additional notes about the information stream, or null when none is set.", "example": "Daily bar revenue at the Pier 9 Bistro" }, "sourceSystem": { "type": [ "string", "null" ], "description": "Source system of the information stream, or null for system-generated streams (e.g. AI forecasts).", "example": "Hospitality POS solutions" }, "sourceSystemSupportEmail": { "type": [ "string", "null" ], "description": "Email address of the source system support, or null for system-generated streams.", "example": "support@hospitality-pos.example.com" }, "createdAt": { "type": "string", "description": "Creation timestamp of the information stream", "example": "2026-07-03 13:23:31" }, "updatedAt": { "type": "string", "description": "Last modification timestamp of the information stream", "example": "2026-07-03 13:23:31" }, "customFeatures": { "type": "array", "items": { "type": "string" }, "description": "Custom features associated with the information stream", "example": [ "feature1", "feature2" ] }, "formulaParents": { "type": "array", "description": "Keys of the parent streams that feed this stream in a formula hierarchy. Always present; empty when the stream has no formula parents.", "items": { "type": "string" } } } } }, "responses": { "200": { "description": "The list of information streams. Without `groupBy` the body is a JSON array\nof stream objects. With `groupBy` the body is an object with `groups` and\n`streams` arrays.\n", "content": { "application/json": { "examples": { "ungrouped": { "summary": "Without groupBy (array of streams)", "value": [ { "key": "bar-revenue-pier9", "isActive": true, "source": "user_provided", "type": "revenue", "granularity": "day", "category": "realized", "departments": [ 1, 2 ], "unit": "currency", "name": "Pier 9 bar revenue", "note": "Daily bar revenue at the Pier 9 Bistro", "sourceSystem": "Hospitality POS solutions", "sourceSystemSupportEmail": "support@hospitality-pos.example.com", "createdAt": "2026-07-03 13:23:31", "updatedAt": "2026-07-03 13:23:31", "customFeatures": [ "feature1", "feature2" ], "formulaParents": [] } ] }, "grouped": { "summary": "With groupBy (groups and streams)", "value": { "groups": [ { "groupId": "18-realized", "label": "Amsterdam", "category": "realized", "departments": [ "01KMQK8WKA3Z5HTY35TNB6B55D" ], "departmentNames": { "01KMQK8WKA3Z5HTY35TNB6B55D": "Department D" }, "streams": [ "bar-revenue-pier9" ] } ], "streams": [ { "key": "bar-revenue-pier9", "isActive": true, "source": "user_provided", "type": "revenue", "granularity": "day", "category": "realized", "departments": [ 1, 2 ], "unit": "currency", "name": "Pier 9 bar revenue", "note": "Daily bar revenue at the Pier 9 Bistro", "sourceSystem": "Hospitality POS solutions", "sourceSystemSupportEmail": "support@hospitality-pos.example.com", "createdAt": "2026-07-03 13:23:31", "updatedAt": "2026-07-03 13:23:31", "customFeatures": [ "feature1", "feature2" ], "formulaParents": [] } ] } } }, "schema": { "oneOf": [ { "type": "array", "description": "Ungrouped result, returned when `groupBy` is not provided.", "items": { "$ref": "#/components/schemas/InformationStreamListItem" } }, { "type": "object", "description": "Grouped result, returned when `groupBy` is provided.", "properties": { "groups": { "type": "array", "description": "The grouping buckets for the requested `groupBy`.", "items": { "type": "object", "properties": { "groupId": { "type": "string", "description": "Identifier of the group; its composition depends on the `groupBy` (e.g. office-and-category).", "example": "18-forecast" }, "label": { "type": "string", "description": "Human-readable label for the group.", "example": "Amsterdam" }, "category": { "type": "string", "description": "Category of the streams in this group.", "example": "forecast" }, "departments": { "type": "array", "description": "Department identifiers covered by this group.", "items": { "type": "string" }, "example": [ "01KMQK8WKA3Z5HTY35TNB6B55D" ] }, "departmentNames": { "type": "object", "description": "Map of department identifier to department name.", "additionalProperties": { "type": "string" }, "example": { "01KMQK8WKA3Z5HTY35TNB6B55D": "Department D" } }, "streams": { "type": "array", "description": "Keys of the information streams in this group.", "items": { "type": "string" }, "example": [ "01KPB4Z004Q6JDNYXPT3739YA3" ] } } } }, "streams": { "type": "array", "description": "The information streams in the result.", "items": { "$ref": "#/components/schemas/InformationStreamListItem" } } } } ] } } } }, "201": { "description": "Response code 201 - CREATED", "content": { "application/json": { "schema": { "type": "object", "description": "Response code 201 - CREATED" } } } }, "400": { "description": "The request was malformed or failed validation.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Bad Request", "status": 400, "detail": "Invalid number: 12c", "message": "Invalid number: 12c", "code": 400 } } } }, "401": { "description": "Missing or invalid authentication.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Unauthorized", "message": "Invalid Token", "status": 401 } } } }, "403": { "description": "The token is valid but lacks the scope required for this operation.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Forbidden", "message": "Access denied.", "status": 403 } } } }, "404": { "description": "The requested resource does not exist. Returned as JSON only when the\nrequest sends `Accept: application/json`; otherwise an HTML error page is\nreturned.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Not Found", "message": "Resource not found", "status": 404 } } } }, "500": { "description": "Unexpected server error.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Internal Server Error", "message": "Server error", "status": 500 } } } }, "503": { "description": "System temporary unavailable due to maintenance", "content": { "application/json": { "schema": { "type": "object", "description": "Response code 503 - unavailable due to maintenance" } } } }, "EmployeeWarning": { "description": "Response code 400 - Bad request. Data may be incorrect but will still be accepted. Will empty any fields containing invalid data when linked to a Dyflexis employee.", "content": { "application/json": { "example": { "status": "warning", "data": [ { "fieldName": "email", "value": "john@example" } ] }, "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"warning\"." }, "data": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string", "description": "The name of the field that contained incorrect data." }, "value": { "type": "string", "description": "The value we tried to save." } } } } } } } } }, "ContractWarning": { "description": "Response code 400 - Bad request. Data may be incorrect but will still be accepted. Will skip all invalid contracts when linked to a Dyflexis employee.", "content": { "application/json": { "example": { "status": "warning", "warnings": [ { "contractReference": "E01", "type": "invalid_data", "data": [ { "startDate": "20-111-0", "endDate": 102 } ] }, { "contractReference": "E02", "type": "overlap", "data": [ "E03", "E04" ] } ] }, "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always \"warning\"" }, "warnings": { "description": "Warning per contract", "type": "array", "items": { "type": "object", "properties": { "contractReference": { "type": "string", "description": "Unique contract reference" }, "type": { "type": "string", "description": "Warning type, either \"invalid_data\" or \"overlap\"", "enum": [ "invalid_data", "overlap" ] }, "data": { "description": "Validation detail for this contract. Depending on the warning type and\nbackend version this is either an object keyed by field name, or an array\n(invalid-field objects for \"invalid_data\", contract references for \"overlap\").\n" } } } } } } } } }, "400_v3": { "description": "Validation failed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "title": "Bad Request", "status": 400, "detail": "Validation Failed", "message": "Validation Failed", "code": 400, "violations": [ { "propertyPath": "employeeId", "title": "This value should not be null.", "type": null } ] } } } }, "400-2": { "description": "Validation failed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "title": "Bad Request", "status": 400, "detail": "Validation Failed", "message": "Validation Failed", "code": 400, "violations": [ { "propertyPath": "name", "title": "This value should not be null.", "type": null } ] } } } }, "401-2": { "description": "Missing or invalid authentication.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Unauthorized", "status": 401, "detail": "Invalid Token", "message": "Invalid Token", "code": 401 } } } }, "403-2": { "description": "The token is valid but lacks the scope required for this operation.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Forbidden", "status": 403, "detail": "Access denied.", "message": "Access denied.", "code": 403 } } } }, "200-2": { "description": "Response code 200 - OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response where top-level keys are granularities (e.g., hour, day)", "additionalProperties": { "type": "object", "description": "Map of timestamp strings to data point objects for that granularity", "additionalProperties": { "type": "object", "properties": { "value": { "type": "number", "description": "The main data point value" }, "lower_bound": { "type": "number", "description": "Lower confidence bound" }, "upper_bound": { "type": "number", "description": "Upper confidence bound" } }, "required": [ "value", "lower_bound", "upper_bound" ] } } }, "example": { "day": { "2026-05-01": { "value": 25.8, "lower_bound": 0, "upper_bound": 0 }, "2026-07-21": { "value": 700, "lower_bound": 0, "upper_bound": 0 } }, "hour": { "2026-07-20 00:00:00": { "value": 100, "lower_bound": 0, "upper_bound": 0 }, "2026-07-20 03:00:00": { "value": 50, "lower_bound": 0, "upper_bound": 0 } }, "week": { "2026-W29": { "value": 300, "lower_bound": 200, "upper_bound": 400 } } } } } }, "400-3": { "description": "Invalid data in request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Invalid request data" } } } } } }, "200-3": { "description": "Response code 200 - OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response code 200 - OK" } } } }, "404-2": { "description": "The requested resource does not exist.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Not Found", "status": 404, "detail": "Not Found", "message": "Not Found", "code": 404 } } } }, "500-2": { "description": "Unexpected server error.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "title": "Internal Server Error", "status": 500, "detail": "Internal Server Error", "message": "Internal Server Error", "code": 500 } } } }, "400_v3_xml": { "description": "Bad request - Validation failed", "content": { "application/xml": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": [ "null", "string" ] }, "context": { "type": "object", "properties": { "field": { "type": [ "null", "string" ], "description": "The field related to the encountered error." } } } } } } } } } } }, "401_xml": { "description": "Invalid authentication token", "content": { "application/xml": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Invalid authentication token", "example": "Unauthorized" } } } } } }, "403_xml": { "description": "Invalid authentication token scope", "content": { "application/xml": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Invalid authentication token scope", "example": "Forbidden" } } } } } }, "503_xml": { "description": "System temporary unavailable due to maintenance", "content": { "application/xml": { "schema": { "type": "object", "description": "Response code 503 - unavailable due to maintenance" } } } } }, "parameters": { "Page": { "name": "page", "in": "query", "required": false, "description": "Page number of the paginated result set. The first page is `1`.", "schema": { "type": "integer", "minimum": 1, "default": 1 } } } } }