Payroll and labor advisory

Goal: feed your payroll software with effective hours, absences and vacation balances for a period, without manual exports.

Required scopes: org:fichajes:read, org:ausencias:read, org:saldos:read.

The three key resources:

GET /v1/work-summaries — the payroll resource: closed workday aggregates per employee and period.
GET /v1/absences — sick leave, vacations and deductions for the period.
GET /v1/vacation-balances — vacation balances for the close.

Work summaries: hours for the period

work-summaries returns one row per employee × period with the aggregates already computed (not check-in events). Filter by period=day|month and a from/to range (≤ 1 year).


curl -s "$KINMU_BASE_URL/work-summaries?period=month&from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer $KINMU_API_KEY"


{
  "data": [
    {
      "employee_id": "a1b2…",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "worked_minutes": 9600,
      "break_minutes": 1200,
      "night_minutes": 300,
      "overtime_minutes": 240,
      "expected_minutes": 9600,
      "balance_minutes": 0,
      "banked_hours_balance_minutes": 120,
      "absences_minutes": 480,
      "source_days": 21
    }
  ],
  "meta": { "next_cursor": null, "has_more": false }
}

Fields relevant to payroll:

Field	Use
`worked_minutes`	Effective time worked.
`night_minutes`	Minutes on the night shift (premiums).
`overtime_minutes`	Overtime for the period.
`expected_minutes`	Theoretical workday per contract.
`balance_minutes`	Difference worked − expected.
`banked_hours_balance_minutes`	Banked hours balance.
`absences_minutes`	Minutes of absence in the period.

Monthly aggregates may be served from consolidated snapshots. If your close depends on data from the current day, account for possible consolidation latency and close over already-completed periods.

Absences for the period

Cross-reference the approved absences that overlap the payroll period to apply leave and deductions:


curl -s "$KINMU_BASE_URL/absences?status=approved&from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer $KINMU_API_KEY"

Each absence carries type as { key, label } (the key is stable: vacation, sick_leave, or your company’s custom types) and days_count. Always use the key in your logic.

Vacation balances

For the annual close or for provisions, query the balances per employee and year:


curl -s "$KINMU_BASE_URL/vacation-balances?year=2026" \
  -H "Authorization: Bearer $KINMU_API_KEY"


{
  "data": [
    {
      "employee_id": "a1b2…",
      "year": 2026,
      "entitled_days": 23,
      "used_days": 10,
      "pending_days": 2,
      "remaining_days": 11,
      "carry_over_days": 0,
      "carry_over_expires_at": null
    }
  ]
}

Monthly close flow

List the active employees for the period

GET /v1/employees?status=active (paginate with cursor if you have more than 100).

Download the month’s work-summaries

GET /v1/work-summaries?period=month&from=…&to=….

Cross-reference the approved absences

GET /v1/absences?status=approved&from=…&to=….

(Optional) Generate the legal time registry

For labor inspection, request the time_registry_monthly report (RD-ley 8/2019):


curl -s -X POST "$KINMU_BASE_URL/reports" \
  -H "Authorization: Bearer $KINMU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "type": "time_registry_monthly", "format": "csv", "params": { "month": "2026-06" } }'

Formats: csv or xlsx (xlsx only for check_ins_export). You’ll receive 202 { "id": "…", "status": "processing" }. Poll GET /v1/reports/{id} until status=completed; then the response includes download_url, a temporary signed URL (TTL 5 min, single use). The signature is the credential: download the file from that URL without an Authorization header:


# 1) get the download_url (only present once status=completed)
DL=$(curl -s "$KINMU_BASE_URL/reports/<id>" \
  -H "Authorization: Bearer $KINMU_API_KEY" | jq -r '.download_url')
 
# 2) download the file from the signed URL (no Bearer; single use, 5 min)
curl -s -L "$DL" -o time-registry-2026-06.csv

The org:informes:read scope is required to request the report. The download_url is single-use and expires in 5 minutes: request it and download it right away.