# Dyflexis API

> REST API for the Dyflexis workforce management platform: employees, scheduling, time clock, payroll, absence, and workload, demand forecasting, staff capacity.

## API reference
OpenAPI 3.1 reference for every Dyflexis endpoint.

 - [Dyflexis API](https://beta-developer.dyflexis.com/openapi.md): Dyflexis is a complete **workforce management platform** that brings staff scheduling, time tracking and attendance, leave and absence, AI-powered demand forecasting, payroll, performance management, skills management, and an employee hub with chat together in one system. The Dyflexis API gives you programmatic access to the workforce data behind that platform, the (automated) staff planning, time tracking, payrolling, absence management, workload information, and staff capacity that Dyflexis manages. Endpoints are organised by resource, **Employees**, **Contracts**, **Time clock**, **Payroll**, **Absence**, **Information streams**, and so on. The version of each endpoint (`v0`, `api2`, `v3`) lives in the URL; you can mix versions in the same integration. ## Base URL ``` https://app.dyflexis.com/{systemName} ``` Replace `{systemName}` with the tenant identifier of the customer you are integrating with, the customer provides this value to you when they connect your integration (see the [`systemName` server variable](#section/Servers) below for details on where to find it). Every server URL in this specification (and any new environment added in the future) starts with this base; new environments extend it with additional path segments rather than introducing a different host. This is enforced by the `rule/server-url-base` lint assertion in `redocly.yaml`. Each version has its own URL prefix under that base: | Version | Prefix | Status | | --- | --- | --- | | v3 | `/api/<resource>/v3/...` | Latest production, preferred for new integrations | | api2 (v2) | `/api2/...` | Stable production, use when no v3 equivalent exists | | v0 | `/api/v0/...` | Legacy, one endpoint kept for existing Business Intelligence consumers | ## Authentication Almost every endpoint requires an API key, sent in the `Authorization` header with the `Token` prefix: ``` Authorization: Token YOUR_AUTH_TOKEN ``` `YOUR_AUTH_TOKEN` is the API key issued to you by Dyflexis. To call an endpoint directly from these docs: open the operation, click **Try it**, and open the **Security** tab of the request panel. **Name** is pre-filled with `Authorization` and **API key** with `Token YOUR_AUTH_TOKEN`; replace `YOUR_AUTH_TOKEN` with your API key, keeping the `Token ` prefix. The key is kept in your browser's session storage only and is cleared when the session ends. ### API scopes Each token is issued with one or more **scopes** that gate which parts of the API it can call. A scope is a named permission on the token (for example `business`, `clock`, `payroll`, `absence`, `external_employees`, `information_lines`); every operation declares the scope it requires, and the scope must be **enabled on your token** before that operation will accept the request. A token without the required scope is rejected with `403 Forbidden`, even when the token itself is otherwise valid. Scopes are issued per integration, you do not pick them yourself. Ask a Dyflexis administrator to enable the scopes you need when you request your token. The required scope is listed on each operation. ## Timezones All date and time values in this API are expressed in the **timezone configured on the customer's Dyflexis tenant**, not UTC and not the partner's local timezone. A shift returned as starting at `09:00` starts at `09:00` in the customer's configured timezone, regardless of where your client is running, and a timestamp you send in is interpreted the same way. The tenant timezone is a per-customer setting; if you integrate with customers in different countries, treat the timezone as a per-tenant property and read or store it alongside the data you process. ## Errors The API returns standard HTTP status codes. Successful responses are in the `2xx` range; client errors in the `4xx` range; server errors in the `5xx` range. | Code | Meaning | | --- | --- | | `200 OK` | Request succeeded | | `201 Created` | Resource created | | `400 Bad Request` | Validation failed or the payload was malformed | | `401 Unauthorized` | Missing or invalid authentication | | `403 Forbidden` | Token does not include the required scope | | `404 Not Found` | Resource or path does not exist | | `429 Too Many Requests` | Rate limit exceeded, back off and retry | | `500 Internal Server Error` | Unexpected server error | | `503 Service Unavailable` | Upstream system temporarily unavailable | Error bodies are returned as `application/json` **only when the request sends an `Accept: application/json` header**; without it the API may return an HTML error page instead, so always send that header. A JSON error body has the fields `title`, `status`, `detail`, `message` (the same text as `detail`), and `code`. Validation failures (`400`) add a `violations` array with one entry per invalid field (`propertyPath`, `title`, `type`). ## Rate limiting Requests are rate-limited per token. When a token exceeds the limit, requests return `429 Too Many Requests`. Implement exponential backoff on `429` and `5xx` responses, and avoid tight polling loops. ## Pagination List endpoints paginate with a `page` query parameter (or a path segment, depending on the version). Where supported, responses include a `_links` block with `self`, `next`, `prev`, `first`, and `last` URLs you can follow without recomputing.

## Guides
Onboarding, quickstart, integration patterns, webhook receiver contract, and the partner process.

 - [Become a partner](https://beta-developer.dyflexis.com/guides/become-a-partner.md)
 - [Use cases](https://beta-developer.dyflexis.com/guides/use-cases.md)
 - [Dyflexis API](https://beta-developer.dyflexis.com/index.html.md)
 - [Quickstart](https://beta-developer.dyflexis.com/guides/quickstart.md)
 - [Webhooks](https://beta-developer.dyflexis.com/guides/webhooks.md)