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.

work-summaries and vacation-balances ignore updated_since (accepted for compatibility, deprecated, removal on 2027-08-27): to refresh a close, request the range again (from/to, year) instead of trying a delta.

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).

If your integration also creates employees, POST /v1/employees may answer 402 billing_required: the subscription is active but the plan has run out of seats. Upgrade the plan in the dashboard; retrying without changing anything returns the same 402. The employee email is unique per company, not globally.

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.