Architecture and resource model

Responsibility split

Responsibility	Customer integration	JobHandy API
Store the API key securely	Yes	No
Schedule polling and synchronization	Yes	No
Map source fields to API fields	Yes	No
Generate and log `X-Request-ID`	Recommended	Echoes or generates
Enforce API-key scope	No	Yes
Validate request schema and business state	No	Yes
Reconcile ambiguous write outcomes	Yes	Provides current resource state
Protect downloaded files after retrieval	Yes	Protects API access and download scope

Resource ownership

Resource	Owning boundary	Public write capabilities
Tenant	API-key scope	No tenant create, update, or delete operation
Division	One tenant	Create and update
Employee	Zero or one tenant; optional division	Create and update supported fields
Order	One tenant and one employee	Read and record one HR decision from the documented state
Incident	Employee in authorized scope	Create, update supported fields, upload permitted attachments
Payroll export document	One tenant	Read metadata and download available file

Write side effects

Operation	Persistent effect	Additional side effect	Dry-run behavior
Create employee	Creates account	Sends password setup email	No account and no email
Update employee	Changes supported fields	None stated by the contract	No persistence
Decide order	Stores final HR decision	Sends corresponding notifications	No decision and no notifications
Create incident	Creates incident	Assigns reporter and lifecycle metadata	No persistence
Update incident	Changes supported incident fields	Server lifecycle rules can apply	No persistence
Upload incident attachments	Stores permitted files	None stated by the contract	Validates without storage
Create division	Creates hierarchy node	None stated by the contract	No persistence
Update division	Changes hierarchy/name/order/cost center	None stated by the contract	No persistence

The OpenAPI contract is authoritative. Do not assume additional emails, notifications, or downstream actions that are not documented.

Identifier relationships

Resource IDs are opaque application identifiers. Do not derive business meaning from their characters or order.

Tenant ID
  -> used for X-Tenant-ID and tenant fields
Division ID
  -> used for parentId and employee divisionId
Employee ID
  -> used by orders and incidents
Order attachment ID
  -> used only with the order attachment download endpoint
Payroll export document ID
  -> used for metadata retrieval and download

The public contract defines request and response behavior. Customer-specific business ownership, schedules, field mappings, and downstream retention remain part of the integration design.

Get Started

Architecture & Concepts

Integration Guides

Operations

System boundary

Responsibility split

Resource ownership

Write side effects

Identifier relationships

Integration model

​System boundary

​Responsibility split

​Resource ownership

​Write side effects

​Identifier relationships

​Integration model

System boundary

Responsibility split

Resource ownership

Write side effects

Identifier relationships

Integration model