Hrmony Embedded API — Admin (EN) (1.0.0)

Download OpenAPI specification:

License: LicenseRef-Hrmony-Proprietary

Hrmony Embedded API — Admin tier. Do not edit by hand.

Mitarbeiter

Create a single employee

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

employeeNumber required	string Personnel number of the employee. Unique within the organisation; duplicate results in 409.
firstName required	string First name of the employee.
lastName required	string Last name of the employee.
externalEmployeeId	string Optional stable identifier of the employee from the partner system. Immutable after creation. Used as the `sub` claim on user tokens (§AU9).

Responses

Request samples

Payload

Content type

application/json

{"employeeNumber": "P-10023",
"firstName": "Anna",
"lastName": "Schmidt",
"externalEmployeeId": "ext-ma-9f72e3"
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
"employeeNumber": "string",
"firstName": "string",
"lastName": "string",
"status": "active",
"externalEmployeeId": "string"
}
}

Fetch a single employee

Authorizations:

clientCredentials

path Parameters

employeeId

required

string <uuid>

UUID of the employee.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"employeeId": "550e8400-e29b-41d4-a716-446655440000",
"organisationId": "550e8400-e29b-41d4-a716-446655440001",
"employeeNumber": "P-10023",
"firstName": "Anna",
"lastName": "Schmidt",
"status": "active"
}
}

List employees

Authorizations:

clientCredentials

query Parameters

limit	integer >= 1 Page size.
cursor	string Opaque cursor from `meta.pagination.nextCursor`.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
"employeeNumber": "string",
"firstName": "string",
"lastName": "string",
"status": "active",
"externalEmployeeId": "string"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Create multiple employees

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

required

Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Payload

Content type

application/json

{"employee": [{"employeeNumber": "string",
"firstName": "string",
"lastName": "string",
"externalEmployeeId": "string"
}
]
}

Response samples

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "employees.create_bulk",
"status": "running",
"pollUrl": "http://example.com",
"createdAt": "2019-08-24T14:15:22Z",
"completedAt": "2019-08-24T14:15:22Z"
}
}

Deactivate employee

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

employeeId required	string <uuid>
deactivatedOn required	string^\d{4}-(0[1-9]\|1[012])$ Service month in `YYYY-MM` format.

Responses

Request samples

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"deactivatedOn": "string"
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"status": "active"
}
}

Reactivate employee

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

employeeId required	string <uuid>
activatedOn required	string^\d{4}-(0[1-9]\|1[012])$ Service month in `YYYY-MM` format.

Responses

Request samples

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"activatedOn": "string"
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"status": "active"
}
}

Set employee master data

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"employeeNumber": "string",
"firstName": "string",
"lastName": "string"
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"status": "active"
}
}

Organisation

Fetch the active organisation

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
"externalCustomerId": "string",
"name": "string"
}
}

Change external customer ID

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

externalCustomerId

required

string

Responses

Request samples

Payload

Content type

application/json

{"externalCustomerId": "string"
}

Response samples

Content type

application/json

{"data": {"organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
"externalCustomerId": "string",
"name": "string"
}
}

Fetch organisation benefit overview

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": [{"benefitType": "essenszuschuss",
"status": "active",
"aktivAb": "string"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Organisation · Essenszuschuss

Activate meal allowance

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": {"organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
"effectiveFrom": "string"
}
}

Block meal allowance

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": {"organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
"effectiveFrom": "string"
}
}

Organisation · Mobilitaet

Activate mobility

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": {"organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
"effectiveFrom": "string"
}
}

Block mobility

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": {"organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
"effectiveFrom": "string"
}
}

Mitarbeiter · Essenszuschuss

Fetch meal allowance configuration values

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"annualValues": [{"year": 0,
"maximumDailyReimbursement": 0,
"maximumMonthlyReimbursement": 0
}
]
}
}

List meal allowance configurations

Authorizations:

clientCredentials

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 Page size.
cursor	string Opaque cursor.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string",
"budget": 0,
"dailyRate": 0,
"employeeContribution": true,
"grossCompensationPayment": true
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

List meal allowance status

Authorizations:

clientCredentials

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 Page size.
cursor	string Opaque cursor.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"status": "active"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Fetch meal allowance configuration

Authorizations:

clientCredentials

path Parameters

employeeId

required

string <uuid>

UUID of the employee.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string",
"budget": 0,
"dailyRate": 0,
"employeeContribution": true,
"grossCompensationPayment": true
}
}

Fetch meal allowance status

Authorizations:

clientCredentials

path Parameters

employeeId

required

string <uuid>

UUID of the employee.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"status": "active"
}
}

Configure meal allowance

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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.
dailyRate required	number decimal places <= 2 >= 0 Monetary amount in Euro with two decimal places.
employeeContribution required	boolean
grossCompensationPayment required	boolean

Responses

Request samples

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string",
"budget": 0,
"dailyRate": 0,
"employeeContribution": true,
"grossCompensationPayment": true
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
}

Configure meal allowance in bulk

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

required

Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Payload

Content type

application/json

{"employee": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string",
"budget": 0,
"dailyRate": 0,
"employeeContribution": true,
"grossCompensationPayment": true
}
]
}

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Activate meal allowance

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
}

Activate meal allowance in bulk

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

employeeId 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

Payload

Content type

application/json

{"employeeId": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Deactivate meal allowance

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
}

Deactivate meal allowance in bulk

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

employeeId 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

Payload

Content type

application/json

{"employeeId": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Mitarbeiter · Mobilitaet

List mobility configurations

Authorizations:

clientCredentials

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 Page size.
cursor	string Opaque cursor.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string",
"budget": 0
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

List mobility status

Authorizations:

clientCredentials

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 Page size.
cursor	string Opaque cursor.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"status": "active"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Fetch mobility configuration

Authorizations:

clientCredentials

path Parameters

employeeId

required

string <uuid>

UUID of the employee.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string",
"budget": 0
}
}

Fetch mobility status

Authorizations:

clientCredentials

path Parameters

employeeId

required

string <uuid>

UUID of the employee.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"status": "active"
}
}

Configure mobility

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string",
"budget": 0
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
}

Configure mobility in bulk

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

required

Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Payload

Content type

application/json

{"employee": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string",
"budget": 0
}
]
}

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Activate mobility

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
}

Activate mobility in bulk

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

employeeId 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

Payload

Content type

application/json

{"employeeId": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Deactivate mobility

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) 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

Payload

Content type

application/json

{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": {"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
}

Deactivate mobility in bulk

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

employeeId 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

Payload

Content type

application/json

{"employeeId": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"effectiveFrom": "string"
}

Response samples

Content type

application/json

{"data": [{"employeeId": "b0e78c8f-8c8b-4410-8293-9239e39d9e17",
"effectiveFrom": "string"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Webhooks

Register webhook

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

url

required

string <uri>

Responses

Request samples

Payload

Content type

application/json

{"url": "http://example.com"
}

Response samples

Content type

application/json

{"data": {"webhookId": "ed71eef4-4c34-46dc-81fe-954e560454fd",
"url": "http://example.com",
"signingSecret": "string",
"registeredAt": "2019-08-24T14:15:22Z"
}
}

Deregister webhook

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

webhookId

required

string <uuid>

Responses

Request samples

Payload

Content type

application/json

{"webhookId": "ed71eef4-4c34-46dc-81fe-954e560454fd"
}

Response samples

Content type

application/json

{"data": {"webhookId": "ed71eef4-4c34-46dc-81fe-954e560454fd"
}
}

List webhooks

Authorizations:

clientCredentials

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 Page size.
cursor	string Opaque cursor.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": [{"webhookId": "ed71eef4-4c34-46dc-81fe-954e560454fd",
"url": "http://example.com",
"registeredAt": "2019-08-24T14:15:22Z"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Lohndaten · Lohndateien

Fetch payroll file formats

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"formate": [{"format": "csv",
"label": "string",
"fields": [{"name": "string",
"label": "string",
"type": "string",
"erforderlich": true
}
]
}
]
}
}

Configure payroll file format

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

required	"csv" (string) or "excel" (string) or "datev" (string) or "lodas" (string) or "sage" (string)
taxExempt	string
clientNumber	string
consultantNumber	string

Responses

Request samples

Payload

Content type

application/json

{"format": "csv",
"taxExempt": "string",
"clientNumber": "string",
"consultantNumber": "string"
}

Response samples

Content type

application/json

{"data": {"format": "csv",
"taxExempt": "string",
"clientNumber": "string",
"consultantNumber": "string"
}
}

Fetch payroll file format

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"format": "csv",
"taxExempt": "string",
"clientNumber": "string",
"consultantNumber": "string"
}
}

List payroll files

Authorizations:

clientCredentials

query Parameters

limit	integer [ 1 .. 200 ] Default: 50 Page size.
cursor	string Opaque cursor.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": [{"payrollFileId": "f7cfda16-c0e0-4429-9fb7-6a64660fd079",
"importMonth": "string",
"correctionVersion": 0,
"format": "csv",
"createdAt": "2019-08-24T14:15:22Z",
"downloadedAt": "2019-08-24T14:15:22Z"
}
],
"meta": {"pagination": {"nextCursor": "string",
"hasMore": true
}
}
}

Download payroll file

Authorizations:

clientCredentials

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
Idempotency-Key	string Optional idempotency key for mutating requests.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Request Body schema: application/json
required

payrollFileId

required

string <uuid>

Responses

Request samples

Payload

Content type

application/json

{"payrollFileId": "f7cfda16-c0e0-4429-9fb7-6a64660fd079"
}

Response samples

Content type

application/json

{"data": {"payrollFileId": "f7cfda16-c0e0-4429-9fb7-6a64660fd079",
"importMonth": "string",
"correctionVersion": 0,
"format": "csv",
"createdAt": "2019-08-24T14:15:22Z",
"downloadedAt": "2019-08-24T14:15:22Z",
"downloadUrl": "http://example.com",
"validUntil": "2019-08-24T14:15:22Z"
}
}

Jobs

Fetch job status

Authorizations:

clientCredentials

path Parameters

jobId

required

string <uuid>

UUID of the job.

header Parameters

Accept-Language required	string Enum: "de" "en" Request language surface — `de` or `en`.
X-Request-Id	string Correlation id; echoed on the response.
traceparent	string W3C trace context.
tracestate	string W3C trace state.
X-Hrmony-Tenant-ID required	string Tenant (organisation) id — required on the admin tier.

Responses

Response samples

Content type

application/json

{"data": {"job": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "employees.create_bulk",
"status": "running",
"pollUrl": "http://example.com",
"createdAt": "2019-08-24T14:15:22Z",
"completedAt": "2019-08-24T14:15:22Z"
}
}
}

Hrmony Embedded API — Admin (EN) (1.0.0)

Mitarbeiter

Create a single employee

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Fetch a single employee

Authorizations:

path Parameters

header Parameters

Responses

Response samples

List employees

Authorizations:

query Parameters

header Parameters

Responses

Response samples

Create multiple employees

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Deactivate employee

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Reactivate employee

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Set employee master data

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Organisation

Fetch the active organisation

Authorizations:

header Parameters

Responses

Response samples

Change external customer ID

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Fetch organisation benefit overview

Authorizations:

header Parameters

Responses

Response samples

Organisation · Essenszuschuss

Activate meal allowance

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Block meal allowance

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required