Manage employee incidents

API 2.0.0: active contract required

POST /incidents requires a contract with status active. Status approved is insufficient. Without an active contract, the request fails with HTTP 422 and EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, including when dryRun=true; no incident is created. Resolve the contract state through the responsible business process before submitting a new request with a new X-Request-ID. Existing incidents remain editable under their existing lifecycle and field restrictions. This new prerequisite applies to creation. The employee activation prerequisite remains documented separately; no precedence between validation errors is specified. The Incidents API supports reporting employee incidents, reading lifecycle state, updating documented editable fields, and uploading permitted attachments.

Types and statuses

Dimension	Values	Ownership
Type	`temporary`, `permanent`	Set on create; update only as documented
Status	`reported`, `in_progress`, `completed`, `archived`	Server-managed
Reporter	`user`, `api_key`	Server-assigned

The public contract exposes status for observation but does not expose a direct arbitrary status field in the patch schema.

Status responsibility

Status	Direct status write through public patch	Attachment upload
`reported`	No; status is server-managed	No
`in_progress`	No; status is server-managed	No
`completed`	No; status is server-managed	Supported only when the incident is editable
`archived`	No; status is server-managed	No

The public contract does not expose a generic status property in IncidentPatch. Synchronize status by reading the incident.

Incident swimlane

Create an incident

{
  "type": "temporary",
  "employee": "690000000000000000000001",
  "dateFrom": "2026-08-26T00:00:00.000Z"
}

The referenced employee must be accessible in the selected tenant context and must already be activated. The API assigns reporter metadata and initial lifecycle state. If the employee exists but has not completed activation, POST /incidents may return 422 EMPLOYEE_NOT_ACTIVATED:

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

For EMPLOYEE_NOT_ACTIVATED, complete activation before retrying. For EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, resolve the active-contract prerequisite first. Before submitting a new create request, ensure both prerequisites are satisfied; do not assume a validation error precedence.

Update supported fields

The patch contract exposes type, dateFrom, and dateUntil. Setting dateUntil closes or schedules completion of an open temporary incident according to server rules.

{
  "dateUntil": "2026-09-02T00:00:00.000Z"
}

Incidents cannot be reopened through this endpoint.

Attachment conditions

POST /incidents/{id}/attachments
Content-Type: multipart/form-data
field: uploads

Constraint	Contract
Incident state	Editable completed incident
File count	1 to 5
Accepted content	`image/*` or `application/pdf`
Complete multipart body	Maximum 5 MiB
Dry run	Validates without storing files

The 5 MiB limit applies to the encoded multipart request, including boundaries and headers.

Upload flow

Data minimization

Upload only documents necessary for the incident process. Do not add unrelated personal data, and protect local source files, retry queues, and downloaded evidence according to the customer’s retention and access rules.

Common failures

Error	Cause	Action
`EMPLOYEE_NOT_ACTIVATED`	Referenced employee has not completed activation	Activate the employee, then submit a new create request
`EMPLOYEE_HAS_NO_ACTIVE_CONTRACT`	422: contract not `active`; also dry run	Resolve contract state through business process
`EMPLOYEE_BLOCKED`	Employee state prevents the operation	Review employee state and business process
`INVALID_STATE_TRANSITION`	Incident cannot accept requested update	Re-read current lifecycle state
`MISSING_ATTACHMENT`	Multipart field is missing	Add one or more `uploads` files
`PAYLOAD_TOO_LARGE`	Complete body exceeds 5 MiB	Reduce file count or size
`UNSUPPORTED_MEDIA_TYPE`	File/request media type is not accepted	Use documented content types

Get Started

Architecture & Concepts

Integration Guides

Operations

API 2.0.0: active contract required

Types and statuses

Status responsibility

Incident swimlane

Create an incident

Update supported fields

Attachment conditions

Upload flow

Data minimization

Common failures

​API 2.0.0: active contract required

​Types and statuses

​Status responsibility

​Incident swimlane

​Create an incident

​Update supported fields

​Attachment conditions

​Upload flow

​Data minimization

​Common failures

API 2.0.0: active contract required

Types and statuses

Status responsibility

Incident swimlane

Create an incident

Update supported fields

Attachment conditions

Upload flow

Data minimization

Common failures