Create an incident

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"
}

At a glance

Property	Behavior
Authentication	Required in X-API-Key
Tenant context	Conditional; referenced employee must resolve inside authorized scope
Employee prerequisite	Referenced employee must be activated
Dry run	Supported with dryRun=true
Request body	application/json; closed schema; maximum documented body 5 MiB
Response	JSON
Primary success	`200`, `201`
Side effects	Creates an incident and assigns reporter/lifecycle metadata; dry run suppresses persistence
Retry guidance	Do not retry blindly; search or reconcile the created incident first

Operational behavior

Reports an employee incident. The API assigns the reporter and lifecycle status. With dryRun=true, the API returns the projected incident without saving it.

The API assigns reporter and initial lifecycle status.
The referenced employee must be visible in the authorized tenant scope and must already be activated.
If the employee exists but is not activated, the API returns 422 EMPLOYEE_NOT_ACTIVATED and does not create an incident.

Employee activation prerequisite

An incident can only be created after the referenced employee has completed activation. An employee who exists and is visible in the API-key scope but is not yet activated produces the following response:

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

Do not retry the same request automatically. Complete the employee activation first, then submit a new create request with a new X-Request-ID.

Common errors

Error code	Meaning
`VALIDATION_ERROR`	Schema or business validation failed
`INVALID_REQUEST_ID`	X-Request-ID is not UUID v4 or v7
`INVALID_API_KEY`	Missing, invalid, deleted, or inactive API key
`TENANT_NOT_IN_SCOPE`	Selected tenant is outside API-key scope
`NOT_FOUND`	Resource is absent or not accessible in scope
`NOT_ACCEPTABLE`	Requested response media type is unavailable
`INVALID_STATE_TRANSITION`	Current lifecycle state does not permit the request
`PAYLOAD_TOO_LARGE`	Complete request exceeds the documented limit
`UNSUPPORTED_MEDIA_TYPE`	Request media type is not accepted
`INVALID_REFERENCE`	Referenced resource is missing or unavailable
`EMPLOYEE_NOT_ACTIVATED`	Referenced employee exists but has not completed activation
`RATE_LIMIT_EXCEEDED`	API-key rate limit was exceeded
`INTERNAL_SERVER_ERROR`	Unexpected server failure

The operation response list and Error handling page are authoritative for complete handling.

Before implementation

Generate and log a new X-Request-ID for the attempt.
Handle every documented response status.
Do not log X-API-Key or unnecessary personal data.
Reconcile current resource state before replaying an ambiguous write.

Related integration guidance

Review the complete process, state, retry, and operational pattern for this operation.

Authorizations

X-API-Key

string

header

required

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.

Headers

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}$

Query Parameters

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.

Example:

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>

required

Incident type. Values are case-sensitive.

Available options:

temporary,

permanent

Minimum string length: 1

Example:

"temporary"

employee

string

required

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

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

Example:

"68a000000000000000000001"

dateFrom

string<date-time>

required

UTC timestamp from which the incident applies.

Minimum string length: 1

Pattern: Z$

Example:

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

Response

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

Employee incident details.

string

required

read-only

Unique incident identifier.

Minimum string length: 1

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

Example:

"730000000000000000000001"

employeeIncidentNumber

integer

required

read-only

Tenant-facing numeric incident number assigned by the server.

Must be a multiple of 1

Example:

37

type

enum<string>

required

Incident type. Values are case-sensitive.

Available options:

temporary,

permanent

Minimum string length: 1

Example:

"temporary"

status

enum<string>

required

read-only

Server-managed incident lifecycle status.

Available options:

reported,

in_progress,

completed,

archived

Minimum string length: 1

Example:

"reported"

employee

string

required

Identifier of the affected employee.

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

Example:

"68a000000000000000000001"

reportedBy

enum<string>

required

read-only

Actor category that originally reported the incident.

Available options:

user,

api_key

Minimum string length: 1

Example:

"api_key"

reportedAt

string<date-time>

required

read-only

UTC timestamp at which the incident was reported.

Minimum string length: 1

Pattern: Z$

Example:

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

dateFrom

string<date-time>

required

UTC timestamp from which the incident applies.

Minimum string length: 1

Pattern: Z$

Example:

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

dateUntil

string<date-time> | null

required

nullable

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

Minimum string length: 1

Pattern: Z$

Example:

null

createdAt

string<date-time>

required

read-only

UTC timestamp at which the incident record was created.

Minimum string length: 1

Pattern: Z$

Example:

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

updatedAt

string<date-time>

required

read-only

UTC timestamp of the latest incident update.

Minimum string length: 1

Pattern: Z$

Example:

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

Last modified on September 2, 2026

Overview

Data Models

Specification

At a glance

Operational behavior

Employee activation prerequisite

Common errors

Before implementation

Related integration guidance

Authorizations

Headers

Query Parameters

Body

Response

​At a glance

​Operational behavior

​Employee activation prerequisite

​Common errors

​Before implementation

Related integration guidance

Authorizations

Headers

Query Parameters

Body

Response

At a glance

Operational behavior

Employee activation prerequisite

Common errors

Before implementation