Upload incident attachments

cURL

curl --request POST \
  --url 'https://api.jobhandy.io/v1/incidents/INCIDENT_ID/attachments?dryRun=true' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --form 'files=@certificate.pdf;type=application/pdf'

const form = new FormData();
form.append('uploads', '<string>');
form.append('uploads.items', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://api.jobhandy.io/v1/incidents/{id}/attachments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.jobhandy.io/v1/incidents/{id}/attachments"

files = { "uploads.items": ("example-file", open("example-file", "rb")) }
payload = { "uploads": "<string>" }
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.jobhandy.io/v1/incidents/{id}/attachments");
var client = new RestClient(options);
var request = new RestRequest("");
request.AlwaysMultipartFormData = true;
request.AddHeader("X-API-Key", "<api-key>");
request.FormBoundary = "---011000010111000001101001";
request.AddParameter("uploads", "<string>");
request.AddFile("uploads.items", "example-file");
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

$headers=@{}
$headers.Add("X-API-Key", "<api-key>")
$headers.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
$response = Invoke-WebRequest -Uri 'https://api.jobhandy.io/v1/incidents/{id}/attachments' -Method POST -Headers $headers -ContentType 'multipart/form-data; boundary=---011000010111000001101001' -Body '-----011000010111000001101001
Content-Disposition: form-data; name="uploads"

<string>
-----011000010111000001101001
Content-Disposition: form-data; name="uploads.items"; filename="example-file"
Content-Type: application/octet-stream

{
  "fileName": "example-file"
}
-----011000010111000001101001--'

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

POST

https://api.jobhandy.io/v1

incidents

{id}

attachments

cURL

curl --request POST \
  --url 'https://api.jobhandy.io/v1/incidents/INCIDENT_ID/attachments?dryRun=true' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --form 'files=@certificate.pdf;type=application/pdf'

const form = new FormData();
form.append('uploads', '<string>');
form.append('uploads.items', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://api.jobhandy.io/v1/incidents/{id}/attachments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.jobhandy.io/v1/incidents/{id}/attachments"

files = { "uploads.items": ("example-file", open("example-file", "rb")) }
payload = { "uploads": "<string>" }
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.jobhandy.io/v1/incidents/{id}/attachments");
var client = new RestClient(options);
var request = new RestRequest("");
request.AlwaysMultipartFormData = true;
request.AddHeader("X-API-Key", "<api-key>");
request.FormBoundary = "---011000010111000001101001";
request.AddParameter("uploads", "<string>");
request.AddFile("uploads.items", "example-file");
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

$headers=@{}
$headers.Add("X-API-Key", "<api-key>")
$headers.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
$response = Invoke-WebRequest -Uri 'https://api.jobhandy.io/v1/incidents/{id}/attachments' -Method POST -Headers $headers -ContentType 'multipart/form-data; boundary=---011000010111000001101001' -Body '-----011000010111000001101001
Content-Disposition: form-data; name="uploads"

<string>
-----011000010111000001101001
Content-Disposition: form-data; name="uploads.items"; filename="example-file"
Content-Type: application/octet-stream

{
  "fileName": "example-file"
}
-----011000010111000001101001--'

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

At a glance

Property	Behavior
Authentication	Required in X-API-Key
Tenant context	Optional narrowing; resource and references must remain in scope
Dry run	Supported with dryRun=true
Request body	multipart/form-data
Response	JSON
Primary success	`200`
Side effects	Stores permitted files; dry run validates without storage
Retry guidance	Do not retry blindly; re-read incident state and result before replay

Operational behavior

Adds image or PDF attachments to an editable completed employee incident. With dryRun=true, the API validates the files without storing them.

Use multipart field uploads with 1 to 5 image or PDF files.
The complete encoded multipart body must not exceed 5 MiB.
The incident must be an editable completed incident.

Common errors

Error code	Meaning
`VALIDATION_ERROR`	Schema or business validation failed
`INVALID_REQUEST_ID`	X-Request-ID is not UUID v4 or v7
`MISSING_ATTACHMENT`	Required multipart upload is missing
`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
`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

Narrows the operation to one tenant in the API key's scope. Any referenced or target resource must be accessible through that tenant. 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}$

Path Parameters

string

required

Incident ID.

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

Example:

"730000000000000000000001"

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

multipart/form-data

The complete request body, including multipart framing where applicable, must not exceed 5 MiB (5,242,880 bytes).

uploads

file[]

required

One to five files. Each file must be a PDF (application/pdf) or an image (image/*).

Required array length: 1 - 5 elements

Response

Returns the incident after upload, or the current incident after successful dry-run validation.

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 August 27, 2026

Overview

Data Models

Specification

At a glance

Operational behavior

Common errors

Before implementation

Related integration guidance

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

​At a glance

​Operational behavior

​Common errors

​Before implementation

Related integration guidance

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

At a glance

Operational behavior

Common errors

Before implementation