> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage employee incidents

> Create incidents, synchronize server-managed lifecycle state, update supported dates, and upload permitted evidence files.

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

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Source as HR / source process
    participant INT as Integration
    participant API as JobHandy API
    participant STORE as JobHandy incident storage

    Source->>INT: Incident data
    INT->>API: POST /incidents?dryRun=true
    API-->>INT: Projected incident
    INT->>API: POST /incidents
    API->>STORE: Persist incident and assign reporter/status
    API-->>INT: Created incident + request ID
    loop Synchronize lifecycle
        INT->>API: GET /incidents/{id}
        API-->>INT: Current server-managed status and dates
    end
    opt Update supported fields
        INT->>API: PATCH /incidents/{id}?dryRun=true
        API-->>INT: Projected incident
        INT->>API: PATCH /incidents/{id}
    end
    opt Editable completed incident permits attachments
        INT->>API: POST /incidents/{id}/attachments
        API-->>INT: Updated result
    end
```

## Create an incident

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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` returns `422 EMPLOYEE_NOT_ACTIVATED`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "EMPLOYEE_NOT_ACTIVATED",
    "message": "The referenced employee is not activated.",
    "requestId": "<request UUID v4 or v7>"
  }
}
```

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Create incident request] --> B{Employee activated?}
    B -- No --> C[422 EMPLOYEE_NOT_ACTIVATED]
    C --> D[Complete employee activation]
    D --> E[Submit a new request with a new X-Request-ID]
    B -- Yes --> F[Validate and create incident]
```

This response is not retryable until the employee has been activated.

## 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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "dateUntil": "2026-09-02T00:00:00.000Z"
}
```

Incidents cannot be reopened through this endpoint.

## Attachment conditions

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[Read incident] --> B{Completed and editable?}
    B -- No --> X[Do not upload]
    B -- Yes --> C[Validate file count, media type, and total body]
    C --> D[Upload with dryRun=true]
    D --> E{Valid?}
    E -- No --> F[Correct files]
    E -- Yes --> G[Upload without dryRun]
    G --> H[Store request ID and result]
```

## 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_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                            |