Vorfall erstellen

curl --request POST \
  --url https://api.jobhandy.io/v1/incidents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "type": "temporary",
  "employee": "68a000000000000000000001",
  "dateFrom": "2026-07-21T00:00:00.000Z"
}
'

{
  "id": "730000000000000000000001",
  "employeeIncidentNumber": 37,
  "type": "temporary",
  "status": "reported",
  "employee": "68a000000000000000000001",
  "reportedBy": "api_key",
  "reportedAt": "2026-07-21T07:30:00.000Z",
  "dateFrom": "2026-07-21T00:00:00.000Z",
  "dateUntil": null,
  "createdAt": "2026-07-21T07:30:00.000Z",
  "updatedAt": "2026-07-21T07:30:00.000Z"
}

POST

https://api.jobhandy.io/v1

incidents

curl --request POST \
  --url https://api.jobhandy.io/v1/incidents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "type": "temporary",
  "employee": "68a000000000000000000001",
  "dateFrom": "2026-07-21T00:00:00.000Z"
}
'

{
  "id": "730000000000000000000001",
  "employeeIncidentNumber": 37,
  "type": "temporary",
  "status": "reported",
  "employee": "68a000000000000000000001",
  "reportedBy": "api_key",
  "reportedAt": "2026-07-21T07:30:00.000Z",
  "dateFrom": "2026-07-21T00:00:00.000Z",
  "dateUntil": null,
  "createdAt": "2026-07-21T07:30:00.000Z",
  "updatedAt": "2026-07-21T07:30:00.000Z"
}

API 2.0.0: Aktiver Vertrag erforderlich

POST /incidents erfordert einen Vertrag mit Status active. Der Status approved reicht nicht aus. Ohne aktiven Vertrag scheitert die Anfrage mit HTTP 422 und EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, auch bei dryRun=true; es wird kein Vorfall erstellt. Klären Sie den Vertragsstatus über den zuständigen Fachprozess, bevor Sie eine neue Anfrage mit neuer X-Request-ID senden. Bestehende Vorfälle bleiben unter ihren bisherigen Lebenszyklus- und Feldbeschränkungen bearbeitbar. Die neue Voraussetzung gilt für das Erstellen. Die Voraussetzung der Mitarbeiteraktivierung bleibt separat dokumentiert; eine Reihenfolge der Validierungsfehler ist nicht festgelegt.

Auf einen Blick

Eigenschaft	Verhalten
Authentifizierung	Erforderlich in `X-API-Key`
Tenant-Kontext	Bedingt; der referenzierte Mitarbeiter muss innerhalb des autorisierten Scopes eindeutig auflösbar sein
Mitarbeitervoraussetzung	Aktivierter Mitarbeiter und Vertragsstatus `active`; `approved` reicht nicht
Dry Run	Unterstützt mit `dryRun=true`
Request-Body	`application/json`; geschlossenes Schema; maximal dokumentierte Body-Größe 5 MiB
Response	JSON
Primärer Erfolg	`200`, `201`
Side Effects	Erstellt einen Vorfall und setzt Melder-/Lifecycle-Metadaten; Dry Run unterdrückt die Speicherung
Retry-Empfehlung	Nicht blind wiederholen; den erstellten Vorfall zuerst suchen oder abgleichen

Betriebsverhalten

Meldet einen Mitarbeitervorfall. Die API setzt Melder und Lifecycle-Status. Mit dryRun=true gibt die API den projizierten Vorfall zurück, ohne ihn zu speichern.

Die API setzt Melder und initialen Lifecycle-Status.
Der referenzierte Mitarbeiter muss im autorisierten Tenant-Scope sichtbar und bereits aktiviert sein.
Existiert der Mitarbeiter, ist aber noch nicht aktiviert, kann die API mit 422 EMPLOYEE_NOT_ACTIVATED antworten und erstellt keinen Vorfall.

Voraussetzung: aktivierter Mitarbeiter

Ein Vorfall kann erst erstellt werden, nachdem der referenzierte Mitarbeiter aktiviert wurde. Existiert der Mitarbeiter und ist er im API-Key-Scope sichtbar, wurde aber noch nicht aktiviert, kann die API wie folgt antworten:

{
  "error": {
    "code": "EMPLOYEE_NOT_ACTIVATED",
    "message": "The referenced employee is not activated.",
    "requestId": "<Request-UUID v4 oder v7>"
  }
}

Wiederholen Sie dieselbe Anfrage nicht automatisch. Schließen Sie zuerst die Aktivierung des Mitarbeiters ab und senden Sie anschließend eine neue Create-Anfrage mit einer neuen X-Request-ID.

Häufige Fehler

Fehlercode	Bedeutung
`VALIDATION_ERROR`	Schema- oder fachliche Validierung ist fehlgeschlagen
`INVALID_REQUEST_ID`	`X-Request-ID` ist keine UUID v4 oder v7
`INVALID_API_KEY`	API-Key fehlt, ist ungültig, gelöscht oder inaktiv
`TENANT_NOT_IN_SCOPE`	Ausgewählter Tenant liegt außerhalb des API-Key-Scopes
`NOT_FOUND`	Ressource fehlt oder ist im Scope nicht zugänglich
`NOT_ACCEPTABLE`	Angeforderter Response-Medientyp ist nicht verfügbar
`INVALID_STATE_TRANSITION`	Aktueller Lifecycle-Status erlaubt die Anfrage nicht
`PAYLOAD_TOO_LARGE`	Vollständiger Request überschreitet das dokumentierte Limit
`UNSUPPORTED_MEDIA_TYPE`	Request-Medientyp wird nicht akzeptiert
`INVALID_REFERENCE`	Referenzierte Ressource fehlt oder ist nicht verfügbar
`EMPLOYEE_NOT_ACTIVATED`	Referenzierter Mitarbeiter existiert, wurde aber noch nicht aktiviert
`EMPLOYEE_HAS_NO_ACTIVE_CONTRACT`	422: Vertrag nicht `active`; auch bei Dry Run; Vertragsstatus fachlich klären
`RATE_LIMIT_EXCEEDED`	Rate Limit des API-Keys wurde überschritten
`INTERNAL_SERVER_ERROR`	Unerwarteter Serverfehler

Die Response-Liste der Operation und die Seite Fehlerbehandlung sind für die vollständige Behandlung maßgeblich.

Vor der Implementierung

Erzeugen und protokollieren Sie für den Versuch eine neue X-Request-ID.
Behandeln Sie jeden dokumentierten Response-Status.
Protokollieren Sie weder X-API-Key noch unnötige personenbezogene Daten.
Gleichen Sie den aktuellen Ressourcenstatus ab, bevor Sie einen mehrdeutigen Write wiederholen.

Zugehöriger Integrationsleitfaden

Prüfen Sie den vollständigen Prozess sowie Status-, Retry- und Betriebsmuster für diese Operation.

Autorisierungen

X-API-Key

string

header

erforderlich

JobHandy integration API key. Send the credential in the X-API-Key header. Treat the key as a secret and use it only from trusted server-side environments.

Header

X-Tenant-ID

string

inactive

optional

not sent by default

If supplied, the header narrows the operation to one tenant in the API key's scope. The referenced employee must be accessible through that tenant. If omitted, the API searches the full scope and infers the tenant from the employee. In interactive clients, use the {{tenantId}} variable when a tenant must be selected. Keep the header disabled when tenant selection is not required.

Pattern: ^[0-9a-fA-F]{24}$

X-Request-ID

string<uuid>

inactive

optional

not sent by default

Optional request identifier. If supplied, it must be a UUID v4 or v7 and is returned unchanged in every response. If omitted, the API generates one. Invalid values return 400 INVALID_REQUEST_ID. If your client uses a {{requestId}} variable, refresh it with a new UUID version 4 or 7 for every HTTP request attempt. Keep the header disabled to let the API generate the request identifier.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Abfrageparameter

dryRun

boolean

inactive

optional

server default: false

not sent by default

When true, the API validates the request without applying the change. The operation's responses specify the returned representation. When omitted, the server uses false.

Beispiel:

true

Body

application/json

The JSON request body must not exceed 5,242,880 bytes.

Fields accepted when reporting an employee incident.

type

enum<string>

erforderlich

Incident type. Values are case-sensitive.

Verfügbare Optionen:

temporary,

permanent

Minimum string length: 1

Beispiel:

"temporary"

employee

string

erforderlich

Identifier of the affected employee. The employee must be accessible in the selected or inferred tenant scope.

Pattern: ^[0-9a-fA-F]{24}$

Beispiel:

"68a000000000000000000001"

dateFrom

string<date-time>

erforderlich

UTC timestamp from which the incident applies.

Minimum string length: 1

Pattern: Z$

Beispiel:

"2026-07-21T00:00:00.000Z"

Antwort

Dry-run validation succeeded. Returns the incident that would be created; it is not stored.

Employee incident details.

string

erforderlich

read-only

Unique incident identifier.

Minimum string length: 1

Pattern: ^[0-9a-fA-F]{24}$

Beispiel:

"730000000000000000000001"

employeeIncidentNumber

integer

erforderlich

read-only

Tenant-facing numeric incident number assigned by the server.

Muss ein Vielfaches sein von 1

Beispiel:

37

type

enum<string>

erforderlich

Incident type. Values are case-sensitive.

Verfügbare Optionen:

temporary,

permanent

Minimum string length: 1

Beispiel:

"temporary"

status

enum<string>

erforderlich

read-only

Server-managed incident lifecycle status.

Verfügbare Optionen:

reported,

in_progress,

completed,

archived

Minimum string length: 1

Beispiel:

"reported"

employee

string

erforderlich

Identifier of the affected employee.

Pattern: ^[0-9a-fA-F]{24}$

Beispiel:

"68a000000000000000000001"

reportedBy

enum<string>

erforderlich

read-only

Actor category that originally reported the incident.

Verfügbare Optionen:

user,

api_key

Minimum string length: 1

Beispiel:

"api_key"

reportedAt

string<date-time>

erforderlich

read-only

UTC timestamp at which the incident was reported.

Minimum string length: 1

Pattern: Z$

Beispiel:

"2026-07-21T07:30:00.000Z"

dateFrom

string<date-time>

erforderlich

UTC timestamp from which the incident applies.

Minimum string length: 1

Pattern: Z$

Beispiel:

"2026-07-21T00:00:00.000Z"

dateUntil

string<date-time> | null

erforderlich

nullable

UTC timestamp until which the incident applies, or null while no end is set.

Minimum string length: 1

Pattern: Z$

Beispiel:

null

createdAt

string<date-time>

erforderlich

read-only

UTC timestamp at which the incident record was created.

Minimum string length: 1

Pattern: Z$

Beispiel:

"2026-07-21T07:30:00.000Z"

updatedAt

string<date-time>

erforderlich

read-only

UTC timestamp of the latest incident update.

Minimum string length: 1

Pattern: Z$

Beispiel:

"2026-07-21T07:30:00.000Z"

Zuletzt geändert am 20. Oktober 2026

Übersicht

Datenmodelle

Spezifikation

API 2.0.0: Aktiver Vertrag erforderlich

Auf einen Blick

Betriebsverhalten

Voraussetzung: aktivierter Mitarbeiter

Häufige Fehler

Vor der Implementierung

Zugehöriger Integrationsleitfaden

Autorisierungen

Header

Abfrageparameter

Body

Antwort

​API 2.0.0: Aktiver Vertrag erforderlich

​Auf einen Blick

​Betriebsverhalten

​Voraussetzung: aktivierter Mitarbeiter

​Häufige Fehler

​Vor der Implementierung

Zugehöriger Integrationsleitfaden

Autorisierungen

Header

Abfrageparameter

Body

Antwort

API 2.0.0: Aktiver Vertrag erforderlich

Auf einen Blick

Betriebsverhalten

Voraussetzung: aktivierter Mitarbeiter

Häufige Fehler

Vor der Implementierung