API docs by Redocly

Hrmony Embedded API — Admin (EN) (1.0.0)

Download OpenAPI specification:

License: LicenseRef-Hrmony-Proprietary

Operations the partner backend performs on behalf of a single customer organization: creating and maintaining employees, configuring benefits, retrieving payroll data, polling jobs.

Authentication — backend token

Backend JWT via the client_credentials grant. Tokens are not issued by this gateway but by its own subdomain, auth.<partner>.hrmony.rest:

curl --request POST \
  --url https://auth.<partner>.hrmony.rest/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data scope='admin:read admin:write'

<partner> is the subdomain assigned to the partner; Hrmony provides client_id and client_secret during onboarding.

The response carries access_token, token_type: Bearer and expires_in. Send the token as Authorization: Bearer <access_token>. This tier has no refresh tokens — once a token expires, request a new one through the same grant; cache it server-side and renew it before it expires.

For this tier the authorization server has exactly two endpoints: the POST /oauth/token above, and GET /.well-known/jwks.json carrying the public key that issued tokens can be verified against. Both live on the auth subdomain rather than on this gateway, so they do not appear in the endpoint list below — the example above is their complete description.

Credentials and scopes

Hrmony issues one client_id/client_secret pair per partner installation. That pair is deliberately valid on all three tiers — it is not an access right in itself, only the permission to have tokens issued. What a call may do is decided by the issued access token alone:

  • A token belongs to exactly one tier. Scopes from two tiers in one request are rejected with 400 invalid_scope, and the other two tiers' gateways reject a token of this tier with 401.
  • A token carries exactly the scopes requested. scope=admin:read yields a read-only token: write endpoints then answer 403 (/errors/forbidden). Every GET is a read, every POST a write. For use cases that only read — a back office, say — this is the intended route: a token of its own with the smallest sufficient scope rather than one token holding every right.
  • The required scope is stated on every operation in this specification as x-required-scope.

On request Hrmony issues several client_id/client_secret pairs for the same installation — one per connecting system, say, so that one can be replaced without touching the others. A credential cannot be restricted to particular tiers or scopes; the separation happens on the token.

The end-user app authenticates differently (a token exchange per employee); that flow is documented on the client tier.

Organization context

Every request on this tier runs in the context of exactly one organization, set through the mandatory header X-Hrmony-Tenant-ID: <organizationId> — not through the path, the query string or the body. A request without that header is rejected with 400 before the operation runs at all. Operations that concern no single organization (creating or listing organizations) live on the partner tier.

Long-running operations

Operations that cannot finish inside one request — bulk endpoints above all — answer 202 Accepted with a job wrapper instead of a result. The wrapper carries a pollUrl; follow it verbatim (it points at GET /v1/jobs/{jobId}). The result is there once status moves from running to successful.

Status

Three levels carry a status, each with its own set of values. They are independent of one another: every value comes from its own record, none is computed from another.

Organization benefit — GET /v1/organization/benefits

  • active — The benefit is enabled for the organization right now.
  • inactive — It is not.

Employee — GET /v1/employees/{employeeId}

  • active — The employee belongs to the organization and can receive benefits.
  • inactive — The employee is no longer active and cannot receive benefits.

Employee benefit — GET /v1/employees/{employeeId}/mealSubsidy/status and the other benefit status endpoints.

  • active — The benefit is effective for that employee.
  • inactive — It is not effective: either a benefit end was set, or the benefit was never configured. This API cannot tell those two apart.

There is no third value here, and there would be no room for one: this endpoint answers for right now, whereas a suspension always covers whole service months in the past — the months between a benefit end and a later activation. For those months GET /v1/benefits/mealSubsidy/employeeStatus/{serviceMonth} on the client tier reports suspended.

How the levels interact

  • While the organization benefit is inactive, configuring or enabling that benefit for an employee answers 403.
  • While the employee is inactive, configuring or enabling any benefit for them answers 409. A benefit end already set is not an obstacle.
  • While the employee benefit is inactive, configuring answers 409; the benefit has to be enabled first.

No status blocks submitting a receipt: receipts are accepted and assessed regardless of all three levels, a service month without an effective benefit simply reimburses nothing. What a block on the organization means for the individual employees is documented on POST /v1/organization/mealSubsidy/disable.

API style

Write endpoints carry a verb in the path: POST …/employees/create rather than POST …/employees. This is deliberate.

The style is hybrid by design:

  • Writes are RPC. The path names the action, the body carries the data.
  • Reads are REST. GET …/{id}, parameters in the URL, no body.

Behind every write endpoint is a command-based model, not a CRUD one. Enabling the meal subsidy or fetching payroll data are not updates to a field on a resource; expressing them as PUT or PATCH would force an unnatural mapping. Many actions are also scheduled rather than immediate: a benefit is activated for an upcoming service month, not right now, and a PATCH on the current state cannot say that.

Reads stay on GET because GET buys something real: responses are cacheable in CDNs and proxies, retries are safe, and a plain lookup needs no request body.

The result is RPC for actions, REST for data.

Errors

All errors follow RFC 9457 Problem Details. Only the type URI is stable and worth branching on — title and detail are for humans and may change. They follow the request language, with one exception: for /errors/unauthorized, /errors/forbidden, /errors/not-found, /errors/throttled, /errors/client-error and /errors/server-error they are always English, for /errors/internal-server-error they can be English. Every error carries a requestId; quote it when raising something with Hrmony.

403 or 404. 403 means the token lacks the required scope, or the current business state forbids the action — a benefit that is not enabled for the organization, for instance.

404 means the resource addressed does not exist or is not yours: another employee's receipt, another partner's organization. We answer both the same way, deliberately indistinguishable — otherwise the status codes would let you probe which ids exist. A 404 therefore does not tell you that the id is unknown.

One error is listed under no single endpoint: /errors/not-found (404) for a path this API does not know, or an HTTP method an endpoint does not offer.

Framework errors and domain errors alike carry type URIs under /errors/….

Responses the API gateway produces itself, and that are none of the cases above, carry the catch-all types /errors/client-error (4xx) and /errors/server-error (5xx). Neither carries a status field: they span several status codes, and the gateway cannot read the actual code inside its template. Branch on the HTTP status code of the response instead.

Throttling (429)

There are no application-level rate limits: no quota per client, per token, per endpoint or per time window, and therefore no RateLimit-* headers either.

The 429 /errors/throttled documented on every operation occurs only when the environment's capacity limit is reached. That limit sits high enough that regular operation never touches it, and it responds to total load across all endpoints — not to a single endpoint or a particular access pattern.

A 429 carries no Retry-After. Treat it as transient and retry with exponentially growing delays plus jitter, not at a fixed interval. The usual retry rules apply: GET is safe to repeat, write endpoints only with the same Idempotency-Key as the first attempt — otherwise you create a second operation.

A 429 says nothing about permissions and does not indicate a blocked account: it means only that this request was not processed and that the same request may succeed later.

Language

For your partner account, the API serves the English variant only: English paths, English field names, English error text. Accept-Language is optional; when sent it must be en. This variant is supported permanently.

The benefit product names are translated like every other term: mealSubsidy and mobility.

Employees

Create a single employee

Creates one employee and responds synchronously with 201. The employee number must be unique inside the organization, otherwise 409 personnel-number-already-taken. For several at once: POST /v1/employees/createBulk.

externalEmployeeId: a given id must be free in the partner account. If it already belongs to an employee, the endpoint answers 409 external-employee-id-already-taken and creates nothing. The value is taken over unchanged — no trimming, no case folding. The 201 carries externalEmployeeId only if the id belongs to the created employee; a missing field does not mean the id is free. If two concurrent requests claim the same id, it belongs to only one of the two employees. Which id an employee has is shown by GET /v1/employees/{employeeId}.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeNumber
required
string

Personnel number of the employee. Unique within the organization; duplicate results in 409.

firstName
required
string

First name of the employee.

lastName
required
string

Last name of the employee.

externalEmployeeId
string [ 1 .. 255 ] characters

Optional stable identifier of the employee from the partner system. Immutable after creation. Used as the sub claim on user tokens.

Responses

Request samples

Content type
application/json
{
  • "employeeNumber": "P-10023",
  • "firstName": "Anna",
  • "lastName": "Schmidt",
  • "externalEmployeeId": "ext-ma-9f72e3"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch a single employee

Authorizations:
clientCredentials
path Parameters
employeeId
required
string <uuid>

UUID of the employee.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List employees

Sort by name: sort=lastName,firstName. Only active employees: filter with status=active; status is not sortable.

Filterable fields

A comma in a value is always an enumeration separator; literal commas are not allowed.

An enumeration takes at most 100 values; more are rejected with 400 /errors/invalid-filter.

An empty value is not allowed, not even as an element of an enumeration.

Field Operators Values Examples
employeeNumber =, , (IN), .contains string ?employeeNumber=<value>
?employeeNumber=<value>,<value2>
?employeeNumber.contains=<value>
lastName =, .contains string ?lastName=<value>
?lastName.contains=<value>
firstName =, .contains string ?firstName=<value>
?firstName.contains=<value>
externalEmployeeId =, , (IN), .contains string ?externalEmployeeId=<value>
?externalEmployeeId=<value>,<value2>
?externalEmployeeId.contains=<value>
status =, , (IN) active, inactive ?status=active
?status=active,inactive

Sortable fields: employeeNumber, lastName, firstName, externalEmployeeId (default employeeNumber)

Authorizations:
clientCredentials
query Parameters
limit
integer >= 1
Default: 50

Page size: default 50, at most 1000. A larger value is rejected with 400 /errors/limit-exceeded.

cursor
string

Opaque cursor from meta.pagination.nextCursor.

employeeNumber
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

employeeNumber.contains
string <= 64 characters

Contains.

lastName
string
lastName.contains
string

Contains.

firstName
string
firstName.contains
string

Contains.

externalEmployeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

externalEmployeeId.contains
string <= 255 characters

Contains.

status
string

Allowed values: active, inactive. Comma-separated for multiple values. A comma always separates values and is never part of a value.

sort
string

Sortable fields: employeeNumber, lastName, firstName, externalEmployeeId. A leading "-" sorts descending, comma-separated for multiple fields. Default: employeeNumber. Entries with equal values always come in the same order. Without writes between pages, paging returns each entry exactly once.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create multiple employees

Creates up to 1000 employees in one call. The response is 202 plus a job; the result arrives via GET /v1/jobs/{jobId}.

Before the 202 the whole request always fails, and no employee is created:

  • 400: schema violations (blank first or last name, 0 or more than 1000 entries, field names of the other language surface), the same externalEmployeeId in two entries of the same request, or entries too large in total.
  • 409 or 422: the same Idempotency-Key is still in flight, or was used with a different body.

After the 202 entries fail individually. The job ends with status: successful even when entries fail; result.data.successful and result.data.failed separate them, and reason is one of employee_number_already_taken, employee_number_duplicated_in_batch, external_employee_id_already_taken or other.

externalEmployeeId: an id that is already taken rejects only its own entry — it appears in result.data.failed with reason: external_employee_id_already_taken, while the remaining entries are created as usual. Only two identical ids within the same request are a 400 before the 202.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
required
string

Idempotency key — required for asynchronous requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "employees": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deactivate employee

If deactivateOn is today or in the past, the employee is inactive immediately after the response. A future date only schedules the deactivation and leaves them active until that day.

Their benefits stay active until the end of the current month — the employee remains entitled to that month, see GET /v1/employees/{employeeId}/mealSubsidy/status.

deactivateOn. A future date schedules the deactivation for that day. A past date is accepted but does not end the benefit retroactively: the benefit end falls in the month we process the request, not in the month of the date. The day decides the last service month — a date from the 2nd onwards ends the benefit with that month, the 1st with the month before.

Receipts carry on. Deactivating stops no review: receipts still in review are reviewed to the end, and the employee can still submit, delete and dispute. A receipt for a month after the benefit end is recorded but reimburses nothing — up to the benefit end they count normally.

Tokens stay valid. Deactivating revokes no tokens. An access token already issued is valid until it expires, a refresh token can still be redeemed, and a fresh token exchange succeeds as well. Locking someone out of the app after they leave is your call: end the session in your app and revoke the refresh token via POST /oauth/revoke.

Payroll. The month the employee leaves in is still settled: they appear in a payroll file generated for that service month. Deactivating changes no payroll file that already exists, and on its own triggers no correction version.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
deactivateOn
required
string <date>

Date of deactivation.

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "deactivateOn": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Reactivate employee

Withdraws a deactivation — the counterpart of deactivate.

If the deactivation had not taken effect yet, it is cancelled and the employee stays active throughout. If they were already inactive, reactivateOn decides: today or in the past reactivates immediately, a future date schedules the reactivation and leaves them inactive until that day. Calling it for an already active employee succeeds and changes nothing.

Benefits do not come back on their own. An employee whose meal subsidy ended with the deactivation is active again but earns nothing. Switch the benefit back on yourself afterwards — POST /v1/employees/mealSubsidy/activate and POST /v1/employees/mobility/activate resume it with the last valid configuration, configure does the same with changed values. The order is binding: while the employee is inactive, those endpoints reject with 409.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
reactivateOn
required
string <date>

Date of reactivation.

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "reactivateOn": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Set employee master data

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
employeeNumber
required
string
firstName
required
string
lastName
required
string

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "employeeNumber": "string",
  • "firstName": "string",
  • "lastName": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Organization

Fetch the active organization

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Change external customer ID

Sets the calling organization’s external customer ID to a new value. The ID is unique per partner account; if another organization already holds it, the endpoint answers 409 external-customer-id-already-taken and changes nothing. The previous value is released by the same call and can be claimed again.

Re-sending the organization’s own current value is a no-op and answers 200, so a retry after a timeout is safe. The following GET /v1/organization already carries the new value.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
externalCustomerId
required
string [ 1 .. 255 ] characters

New stable customer ID from the partner CRM. Unique per partner account; the previous value is released.

Responses

Request samples

Content type
application/json
{
  • "externalCustomerId": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch organization benefit overview

The organization's benefits with their current activation state. status is active while the benefit is enabled for the organization right now.

activeFrom is the service month of the relevant enablement period: the running one, otherwise a scheduled future one, otherwise the most recent past one. With status: inactive it is therefore ambiguous — it may mean the benefit is enabled from that future month, or that it was enabled until some point in the past. A scheduled block is not represented here.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Organization · Meal Subsidy

Activate Meal Subsidy

Enables the meal subsidy for the organization from the service month effectiveFrom on. effectiveFrom must be the current or a future service month; an earlier one is rejected with 422 /errors/effective-date-in-the-past. A repeated call for a month the benefit is already enabled for changes nothing.

Enabling is the precondition for configuring the benefit per employee — while the organization is not enabled, the employee endpoints answer 403.

Enabling configures nobody. It opens the benefit for the organization; every employee still needs POST /v1/employees/mealSubsidy/configure. This matters most after a block: re-enabling does not revive the employees whose benefit the block ended — see the block endpoint.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Block Meal Subsidy

Blocks the meal subsidy for the organization. effectiveFrom is the first service month without the benefit — the last month still covered is the one before it. effectiveFrom must be the current or a future service month; an earlier one is rejected with 422 /errors/effective-date-in-the-past. Blocking the current month — the earliest value allowed — therefore ends the benefit with the previous one: the month already running is no longer covered.

A block ends the benefit for every employee. Per employee a benefit end is set to the last covered month, and any configuration change or pause planned beyond it is annulled. That fan-out runs after the response: the 200 confirms the block, not its per-employee effect.

Re-enabling does not restore them. After block and enable, every employee has to be activated again — POST /v1/employees/mealSubsidy/activate, or configure if the values change. Enabling only reopens the benefit for the organization.

Receipts are unaffected. Employees can still submit receipts for a blocked benefit, and those receipts are still reviewed — but a service month in which the benefit is not active reimburses nothing. A change to a month already transmitted to payroll triggers a payroll late correction.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Organization · Mobility

Activate Mobility

Enables mobility for the organization from the service month effectiveFrom on. effectiveFrom must be the current or a future service month; an earlier one is rejected with 422 /errors/effective-date-in-the-past. A repeated call for a month the benefit is already enabled for changes nothing.

Enabling is the precondition for configuring the benefit per employee — while the organization is not enabled, the employee endpoints answer 403.

Enabling configures nobody. It opens the benefit for the organization; every employee still needs POST /v1/employees/mobility/configure. This matters most after a block: re-enabling does not revive the employees whose benefit the block ended — see the block endpoint.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Block Mobility

Blocks mobility for the organization. effectiveFrom is the first service month without the benefit — the last month still covered is the one before it. effectiveFrom must be the current or a future service month; an earlier one is rejected with 422 /errors/effective-date-in-the-past. Blocking the current month — the earliest value allowed — therefore ends the benefit with the previous one: the month already running is no longer covered.

A block ends the benefit for every employee. Per employee a benefit end is set to the last covered month, and any configuration change or pause planned beyond it is annulled. That fan-out runs after the response: the 200 confirms the block, not its per-employee effect.

Re-enabling does not restore them. After block and enable, every employee has to be activated again — POST /v1/employees/mobility/activate, or configure if the values change. Enabling only reopens the benefit for the organization.

Receipts are unaffected. Employees can still submit receipts for a blocked benefit, and those receipts are still reviewed — but a service month in which the benefit is not active reimburses nothing. A change to a month already transmitted to payroll triggers a payroll late correction.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Employees · Meal Subsidy

List Meal Subsidy per employee

One entry per employee of the organization, whatever the employee status, with the meal subsidy under mealSubsidy. A newly created employee appears immediately, with meal subsidy status inactive. A single entry is available from GET /v1/employees/{employeeId}/mealSubsidy.

Filterable fields

A comma in a value is always an enumeration separator; literal commas are not allowed.

An enumeration takes at most 100 values; more are rejected with 400 /errors/invalid-filter.

An empty value is not allowed, not even as an element of an enumeration.

Field Operators Values Examples
employeeId =, , (IN) uuid ?employeeId=<uuid>
?employeeId=<uuid>,<uuid2>
lastName =, .contains string ?lastName=<value>
?lastName.contains=<value>
firstName =, .contains string ?firstName=<value>
?firstName.contains=<value>
employeeNumber =, , (IN), .contains string ?employeeNumber=<value>
?employeeNumber=<value>,<value2>
?employeeNumber.contains=<value>
status =, , (IN) active, inactive ?status=active
?status=active,inactive
externalEmployeeId =, , (IN), .contains string ?externalEmployeeId=<value>
?externalEmployeeId=<value>,<value2>
?externalEmployeeId.contains=<value>
mealSubsidy.status =, , (IN), .ne active, inactive ?mealSubsidy.status=active
?mealSubsidy.status=active,inactive
?mealSubsidy.status.ne=active

Sortable fields: lastName, firstName, employeeNumber, externalEmployeeId (default lastName,firstName)

Authorizations:
clientCredentials
query Parameters
limit
integer >= 1
Default: 50

Page size: default 50, at most 1000. A larger value is rejected with 400 /errors/limit-exceeded.

cursor
string

Opaque cursor from meta.pagination.nextCursor.

employeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

lastName
string
lastName.contains
string

Contains.

firstName
string
firstName.contains
string

Contains.

employeeNumber
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

employeeNumber.contains
string <= 64 characters

Contains.

status
string

Allowed values: active, inactive. Comma-separated for multiple values. A comma always separates values and is never part of a value.

externalEmployeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

externalEmployeeId.contains
string <= 255 characters

Contains.

mealSubsidy.status
string

Allowed values: active, inactive. Comma-separated for multiple values. A comma always separates values and is never part of a value.

mealSubsidy.status.ne
string
Enum: "active" "inactive"

Not equal.

sort
string

Sortable fields: lastName, firstName, employeeNumber, externalEmployeeId. A leading "-" sorts descending, comma-separated for multiple fields. Default: lastName,firstName. Entries with equal values always come in the same order. Without writes between pages, paging returns each entry exactly once.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch the Meal Subsidy of an employee

One entry as in GET /v1/employees/mealSubsidy, for one employee.

Authorizations:
clientCredentials
path Parameters
employeeId
required
string <uuid>

UUID of the employee.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch Meal Subsidy configuration values

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Meal Subsidy configurations Deprecated

Deprecated. Use GET /v1/employees/mealSubsidy instead.

Filterable fields

A comma in a value is always an enumeration separator; literal commas are not allowed.

An enumeration takes at most 100 values; more are rejected with 400 /errors/invalid-filter.

An empty value is not allowed, not even as an element of an enumeration.

Field Operators Values Examples
employeeId =, , (IN) uuid ?employeeId=<uuid>
?employeeId=<uuid>,<uuid2>

Sortable fields: employeeId (default employeeId)

Authorizations:
clientCredentials
query Parameters
limit
integer >= 1
Default: 50

Page size: default 50, at most 1000. A larger value is rejected with 400 /errors/limit-exceeded.

cursor
string

Opaque cursor from meta.pagination.nextCursor.

employeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

sort
string

Sortable fields: employeeId. A leading "-" sorts descending, comma-separated for multiple fields. Default: employeeId. Entries with equal values always come in the same order. Without writes between pages, paging returns each entry exactly once.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

List Meal Subsidy status Deprecated

Deprecated. Use GET /v1/employees/mealSubsidy instead.

Returns the status of the benefit, not of the employee. The two may differ: after an employee is deactivated the benefit stays active until the end of the current month, because the employee remains entitled to that month. The employee status is available from GET /v1/employees/{employeeId}.

Filterable fields

A comma in a value is always an enumeration separator; literal commas are not allowed.

An enumeration takes at most 100 values; more are rejected with 400 /errors/invalid-filter.

An empty value is not allowed, not even as an element of an enumeration.

Field Operators Values Examples
employeeId =, , (IN) uuid ?employeeId=<uuid>
?employeeId=<uuid>,<uuid2>

Sortable fields: employeeId (default employeeId)

Authorizations:
clientCredentials
query Parameters
limit
integer >= 1
Default: 50

Page size: default 50, at most 1000. A larger value is rejected with 400 /errors/limit-exceeded.

cursor
string

Opaque cursor from meta.pagination.nextCursor.

employeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

sort
string

Sortable fields: employeeId. A leading "-" sorts descending, comma-separated for multiple fields. Default: employeeId. Entries with equal values always come in the same order. Without writes between pages, paging returns each entry exactly once.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch Meal Subsidy configuration Deprecated

Deprecated. Use GET /v1/employees/{employeeId}/mealSubsidy instead.

Authorizations:
clientCredentials
path Parameters
employeeId
required
string <uuid>

UUID of the employee.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch Meal Subsidy status

Returns the status of the benefit, not of the employee. The two may differ: after an employee is deactivated the benefit stays active until the end of the current month, because the employee remains entitled to that month. The employee status is available from GET /v1/employees/{employeeId}.

Authorizations:
clientCredentials
path Parameters
employeeId
required
string <uuid>

UUID of the employee.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Configure Meal Subsidy

Sets an employee’s meal subsidy values as of the service month effectiveFrom. Amounts in euro. Earlier months stay untouched; a service month in the past is rejected with 422. An ended meal subsidy cannot be configured (409) — reactivate it first. An unknown employee yields 404.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

budget
required
number decimal places <= 2 [ 0 .. 100000 ]

Monetary amount in Euro with two decimal places.

dailyRate
required
number decimal places <= 2 [ 0 .. 1000 ]

Monetary amount in Euro with two decimal places.

employeeContribution
required
boolean
grossCompensationPayment
required
boolean

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "effectiveFrom": "2026-09",
  • "budget": 108,
  • "dailyRate": 7.5,
  • "employeeContribution": true,
  • "grossCompensationPayment": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Configure Meal Subsidy in bulk

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
required
string

Idempotency key — required for asynchronous requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "employees": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Activate Meal Subsidy

Withdraws a previously set benefit end and resumes the meal subsidy as of the service month effectiveFrom with the last valid configuration — the counterpart of deactivate.

When to use: when an employee is to receive the meal subsidy unchanged again after a deactivation. If the daily rate, budget or employee contribution are to change at the same time, configure is the right endpoint — it withdraws a benefit end as well. The first activation also goes through configure; an employee without a configuration is rejected here with 409.

Effect: if the benefit end lies in the past, the months up to effectiveFrom are recorded as a pause — the employee status on the client tier reports suspended for those months. A benefit end in the future is simply dropped and the meal subsidy continues. Calling it again for an already active employee succeeds and changes nothing. If no configuration is in effect yet — for example because the first configuration was created for a future service month — the next planned configuration is applied.

effectiveFrom must be the current or a future service month (422 otherwise). An unknown employee yields 404.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Activate Meal Subsidy in bulk

Withdraws a previously set benefit end for up to 1000 employees and resumes the meal subsidy as of effectiveFrom with each employee's last valid configuration — the counterpart of deactivateBulk. The response is 202 plus a job; the result arrives via GET /v1/jobs/{jobId}. Entries fail individually: reason is among others no_configuration_exists (never configured — first activation goes through configureBulk), effective_date_in_past and employee_left_organization. If the daily rate, budget or employee contribution are to change at the same time, configureBulk is the right endpoint.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
required
string

Idempotency key — required for asynchronous requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeIds
required
Array of strings <uuid> [ 1 .. 1000 ] items [ items <uuid > ]
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "employeeIds": [
    ],
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deactivate Meal Subsidy

Ends an employee’s meal subsidy. effectiveFrom is the first month without the benefit, so the last month covered is the one before it. Calling it again with the same effectiveFrom succeeds and changes nothing. A planned end can be brought forward; if an earlier end is already planned, the endpoint answers 409. An unknown employee yields 404.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deactivate Meal Subsidy in bulk

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
required
string

Idempotency key — required for asynchronous requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeIds
required
Array of strings <uuid> [ 1 .. 1000 ] items [ items <uuid > ]
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "employeeIds": [
    ],
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Employees · Mobility

List Mobility per employee

One entry per employee of the organization, whatever the employee status, with mobility under mobility. A newly created employee appears immediately, with mobility status inactive. A single entry is available from GET /v1/employees/{employeeId}/mobility.

Filterable fields

A comma in a value is always an enumeration separator; literal commas are not allowed.

An enumeration takes at most 100 values; more are rejected with 400 /errors/invalid-filter.

An empty value is not allowed, not even as an element of an enumeration.

Field Operators Values Examples
employeeId =, , (IN) uuid ?employeeId=<uuid>
?employeeId=<uuid>,<uuid2>
lastName =, .contains string ?lastName=<value>
?lastName.contains=<value>
firstName =, .contains string ?firstName=<value>
?firstName.contains=<value>
employeeNumber =, , (IN), .contains string ?employeeNumber=<value>
?employeeNumber=<value>,<value2>
?employeeNumber.contains=<value>
status =, , (IN) active, inactive ?status=active
?status=active,inactive
externalEmployeeId =, , (IN), .contains string ?externalEmployeeId=<value>
?externalEmployeeId=<value>,<value2>
?externalEmployeeId.contains=<value>
mobility.status =, , (IN), .ne active, inactive ?mobility.status=active
?mobility.status=active,inactive
?mobility.status.ne=active

Sortable fields: lastName, firstName, employeeNumber, externalEmployeeId (default lastName,firstName)

Authorizations:
clientCredentials
query Parameters
limit
integer >= 1
Default: 50

Page size: default 50, at most 1000. A larger value is rejected with 400 /errors/limit-exceeded.

cursor
string

Opaque cursor from meta.pagination.nextCursor.

employeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

lastName
string
lastName.contains
string

Contains.

firstName
string
firstName.contains
string

Contains.

employeeNumber
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

employeeNumber.contains
string <= 64 characters

Contains.

status
string

Allowed values: active, inactive. Comma-separated for multiple values. A comma always separates values and is never part of a value.

externalEmployeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

externalEmployeeId.contains
string <= 255 characters

Contains.

mobility.status
string

Allowed values: active, inactive. Comma-separated for multiple values. A comma always separates values and is never part of a value.

mobility.status.ne
string
Enum: "active" "inactive"

Not equal.

sort
string

Sortable fields: lastName, firstName, employeeNumber, externalEmployeeId. A leading "-" sorts descending, comma-separated for multiple fields. Default: lastName,firstName. Entries with equal values always come in the same order. Without writes between pages, paging returns each entry exactly once.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch the Mobility of an employee

One entry as in GET /v1/employees/mobility, for one employee.

Authorizations:
clientCredentials
path Parameters
employeeId
required
string <uuid>

UUID of the employee.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Mobility configurations Deprecated

Deprecated. Use GET /v1/employees/mobility instead.

Filterable fields

A comma in a value is always an enumeration separator; literal commas are not allowed.

An enumeration takes at most 100 values; more are rejected with 400 /errors/invalid-filter.

An empty value is not allowed, not even as an element of an enumeration.

Field Operators Values Examples
employeeId =, , (IN) uuid ?employeeId=<uuid>
?employeeId=<uuid>,<uuid2>

Sortable fields: employeeId (default employeeId)

Authorizations:
clientCredentials
query Parameters
limit
integer >= 1
Default: 50

Page size: default 50, at most 1000. A larger value is rejected with 400 /errors/limit-exceeded.

cursor
string

Opaque cursor from meta.pagination.nextCursor.

employeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

sort
string

Sortable fields: employeeId. A leading "-" sorts descending, comma-separated for multiple fields. Default: employeeId. Entries with equal values always come in the same order. Without writes between pages, paging returns each entry exactly once.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

List Mobility status Deprecated

Deprecated. Use GET /v1/employees/mobility instead.

Returns the status of the benefit, not of the employee. The two may differ: after an employee is deactivated the benefit stays active until the end of the current month, because the employee remains entitled to that month. The employee status is available from GET /v1/employees/{employeeId}.

Filterable fields

A comma in a value is always an enumeration separator; literal commas are not allowed.

An enumeration takes at most 100 values; more are rejected with 400 /errors/invalid-filter.

An empty value is not allowed, not even as an element of an enumeration.

Field Operators Values Examples
employeeId =, , (IN) uuid ?employeeId=<uuid>
?employeeId=<uuid>,<uuid2>

Sortable fields: employeeId (default employeeId)

Authorizations:
clientCredentials
query Parameters
limit
integer >= 1
Default: 50

Page size: default 50, at most 1000. A larger value is rejected with 400 /errors/limit-exceeded.

cursor
string

Opaque cursor from meta.pagination.nextCursor.

employeeId
string

Comma-separated for multiple values. A comma always separates values and is never part of a value.

sort
string

Sortable fields: employeeId. A leading "-" sorts descending, comma-separated for multiple fields. Default: employeeId. Entries with equal values always come in the same order. Without writes between pages, paging returns each entry exactly once.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch Mobility configuration Deprecated

Deprecated. Use GET /v1/employees/{employeeId}/mobility instead.

Authorizations:
clientCredentials
path Parameters
employeeId
required
string <uuid>

UUID of the employee.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch Mobility status Deprecated

Deprecated. Use GET /v1/employees/{employeeId}/mobility instead.

Returns the status of the benefit, not of the employee. The two may differ: after an employee is deactivated the benefit stays active until the end of the current month, because the employee remains entitled to that month. The employee status is available from GET /v1/employees/{employeeId}.

Authorizations:
clientCredentials
path Parameters
employeeId
required
string <uuid>

UUID of the employee.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Configure Mobility

Sets an employee’s mobility budget as of the service month effectiveFrom. Amounts in euro. The budget must be at least €1; a lower value is rejected with 422. Earlier months stay untouched; a service month in the past is rejected with 422. Ended mobility cannot be configured (409) — reactivate it first. An unknown employee yields 404.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

budget
required
number decimal places <= 2 >= 0

Monetary amount in Euro with two decimal places.

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "effectiveFrom": "2026-09",
  • "budget": 49
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Configure Mobility in bulk

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
required
string

Idempotency key — required for asynchronous requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "employees": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Activate Mobility

Withdraws a previously set benefit end and resumes mobility as of the service month effectiveFrom with the last valid configuration — the counterpart of deactivate.

When to use: when an employee is to receive mobility unchanged again after a deactivation. If the total budget is to change at the same time, configure is the right endpoint — it withdraws a benefit end as well. The first activation also goes through configure; an employee without a configuration is rejected here with 409.

Effect: if the benefit end lies in the past, the months up to effectiveFrom are recorded as a pause — the employee status on the client tier reports suspended for those months. A benefit end in the future is simply dropped and mobility continues. Calling it again for an already active employee succeeds and changes nothing. If no configuration is in effect — for example a configuration created for a future service month, or right after a deactivation — the newest configuration up to effectiveFrom is applied, otherwise the earliest one.

effectiveFrom must be the current or a future service month (422 otherwise). An unknown employee yields 404.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Activate Mobility in bulk

Withdraws a previously set benefit end for up to 1000 employees and resumes mobility as of effectiveFrom with each employee's last valid configuration — the counterpart of deactivateBulk. The response is 202 plus a job; the result arrives via GET /v1/jobs/{jobId}. Entries fail individually: reason is among others no_configuration_exists (never configured — first activation goes through configureBulk), effective_date_in_past and employee_left_organization. If the total budget is to change at the same time, configureBulk is the right endpoint.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
required
string

Idempotency key — required for asynchronous requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeIds
required
Array of strings <uuid> [ 1 .. 1000 ] items [ items <uuid > ]
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "employeeIds": [
    ],
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deactivate Mobility

Ends an employee’s mobility. effectiveFrom is the first month without the benefit, so the last month covered is the one before it. Calling it again with the same effectiveFrom succeeds and changes nothing. A planned end can be brought forward; if an earlier end is already planned, the endpoint answers 409. An unknown employee yields 404.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeId
required
string <uuid>
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deactivate Mobility in bulk

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
required
string

Idempotency key — required for asynchronous requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
employeeIds
required
Array of strings <uuid> [ 1 .. 1000 ] items [ items <uuid > ]
effectiveFrom
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

Responses

Request samples

Content type
application/json
{
  • "employeeIds": [
    ],
  • "effectiveFrom": "2026-09"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Payroll · Payroll Files

Fetch payroll file formats

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Configure payroll file format

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
format
required
string
Enum: "csv" "excel" "lodas" "lohnGehalt" "sage"

Payroll file format.

clientNumber
string

The end customer's client number in the payroll system. Required only for the DATEV formats lodas and lohnGehalt.

consultantNumber
string

The tax consultancy's consultant number in the payroll system. Required only for the DATEV formats lodas and lohnGehalt.

required
Array of objects non-empty

Pay types per benefit. At least one entry.

Responses

Request samples

Content type
application/json
{
  • "format": "csv",
  • "clientNumber": "12345",
  • "consultantNumber": "1234567",
  • "benefits": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch payroll file format

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List payroll files

Authorizations:
clientCredentials
query Parameters
limit
integer >= 1
Default: 50

Page size: default 50, at most 1000. A larger value is rejected with 400 /errors/limit-exceeded.

cursor
string

Opaque cursor from meta.pagination.nextCursor.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Retrieve payroll file download URL

Creates a fresh presigned download URL for the payroll file addressed by importMonth, benefitType and version, and returns it synchronously. The URL expires after 15 minutes; calling again creates a new one.

This call writes. The first retrieval of a version sets its downloadedAt — the only way that field is ever set; later retrievals of the same version leave it unchanged.

Authorizations:
clientCredentials
header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

Idempotency-Key
string

Optional idempotency key for mutating requests.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Request Body schema: application/json
required
importMonth
required
string^\d{4}-(0[1-9]|1[012])$

Service month in YYYY-MM format.

benefitType
required
string
Enum: "meal_subsidy" "mobility"

Benefit type.

version
required
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "importMonth": "2026-09",
  • "benefitType": "meal_subsidy",
  • "version": 1
}

Response samples

Content type
application/json
{}

Jobs

Fetch job status

Authorizations:
clientCredentials
path Parameters
jobId
required
string <uuid>

UUID of the job.

header Parameters
Accept-Language
string
Value: "en"

Optional. This deployment serves the English language surface only; the only accepted value is en.

X-Request-Id
string

Correlation id; echoed on the response.

traceparent
string

W3C trace context — echoed back when the request supplied it. The API never generates one of its own.

tracestate
string

W3C trace state — echoed back when the request supplied it.

X-Hrmony-Tenant-ID
required
string

Tenant (organization) id — required on the admin tier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}