Retrieve payroll export documents

Payroll export documents are read-only through the Public API. The API exposes metadata and a download operation; it does not expose export generation or deletion.

Supported formats

sap_hcm
personio_csv
hrworks_csv
diamant_software_diamant_4
universal_csv
universal_txt
datev_lodas
datev_lug

Values are case-sensitive.

Retrieval swimlane

List documents

curl --get 'https://api.jobhandy.io/v1/payroll/export-documents' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-ID: {{tenantId}}' \
  --data-urlencode 'filter=type=datev_lodas AND startMonth="2026-01" AND endMonth="2026-01"'

Metadata fields

Field	Meaning
`id`	Stable document identifier for metadata and download
`tenant`	Owning tenant
`type`	Export format
`startMonth`	First covered payroll month in `YYYY-MM`
`endMonth`	Last covered payroll month in `YYYY-MM`
`fileName`	Download filename, or `null` when no file was produced
`mimeType`	Media type derived from the export format
`createdAt`, `updatedAt`	UTC metadata timestamps

Download safely

GET /payroll/export-documents/{id}/download

Read metadata

Confirm tenant, type, month range, filename, and media type.

Check file availability

Do not request a file when fileName is null.

Download

Inspect HTTP status and Content-Type before writing the response as a file.

Validate downstream format

Apply the payroll system’s encoding, delimiter, field, and period checks before import.

Persist processing state

Store document ID, content metadata, request ID, import timestamp, and outcome.

Availability and scheduling

The public OpenAPI contract does not define the export-generation schedule, retention period, or a universal polling interval. Do not invent a cadence from createdAt. Use the customer-specific payroll process and treat document metadata as the source for availability.

Download failures

Status / error	Action
`404 FILE_NOT_FOUND`	Re-read metadata and confirm that a file exists
`502 BAD_GATEWAY`	Retry the download with bounded backoff
`503 SERVICE_UNAVAILABLE`	Retry the download with bounded backoff
`504 GATEWAY_TIMEOUT`	Retry the download; discard incomplete data
`429 RATE_LIMIT_EXCEEDED`	Honor `Retry-After`

Downloaded payroll data must be protected by the destination system’s access, retention, and deletion controls.

Get Started

Architecture & Concepts

Integration Guides

Operations

Retrieve payroll export documents

Supported formats

Retrieval swimlane

List documents

Metadata fields

Download safely

Availability and scheduling

Download failures

​Supported formats

​Retrieval swimlane

​List documents

​Metadata fields

​Download safely

​Availability and scheduling

​Download failures

Supported formats

Retrieval swimlane

List documents

Metadata fields

Download safely

Availability and scheduling

Download failures