API at a glance
An owner or admin creates a key and sends it as a Bearer token. That credential can read hours, punches, shifts, approval status, leave and directory data for its company.
No endpoint changes roster, punch or approval data. Editing and approval remain in Vaktos.
Use the same calculated figures across outputs
API timesheets use the same aggregation as the CSV and printable worksheet. Each company manages and revokes its own credentials.
Use require_approved=1 when a process must reject open periods. In-app CSV is likewise available only after approval.
Credential design
- Company-scoped. The credential determines the company, with no caller-supplied company ID.
- Broad
readscope. Keys are issued with a single read scope rather than per-endpoint permissions; every listed endpoint is available to a valid key. - Displayed once. Vaktos stores a hash and visible prefix; a lost key must be replaced.
- Immediately revocable. An owner or admin can remove access at any time.
- Rate limited. Each key allows 600 requests per minute; requests beyond that limit receive
429. - Bearer authentication and JSON. Send
Authorization: Bearer <API_KEY>; responses include an HTTP status and{ok: true/false}. - Read-only. External callers cannot alter shifts, punches, leave or approvals.
Available data
- Timesheets — one row per person per week or month, with worked, paid, planned, overtime, evening, night, weekend, contract hours, and period status.
- Time entries — raw punches, including voids, with a since cursor for incremental sync.
- Periods — open and approved weeks or months, including the approval time.
- Shifts — workplace, department, person, and status filters, including drafts and history for an individual shift.
- Leave — approved absences by default, with other statuses available on request.
- Directory — people, departments, workplaces, contacts, and roles for interpreting the returned data.
Read an approved payroll period
- Call
timesheet-periodsto check whether the period is open or approved. - Request
timesheets?period=month&month=2026-09&require_approved=1; an open period returns409. - Import the approved rows into your own process. The figures match the Vaktos CSV.
Punch and shift timestamps use UTC; timesheet windows follow local dates in the organisation’s timezone. The API provides generic HTTPS access rather than a named prebuilt integration.
Important details
- This is data access, not a catalogue of payroll, POS, PMS or HRIS connectors.
- CSV, printable worksheets and API timesheets share the same hours calculation.
- Without
require_approved, callers can read an open period; in-app CSV requires approval. - The API does not create payslips, calculate tax or update external systems on your behalf.
Using MarRest? Linked teams keep punching, time review and CSV export in MarRest. This timesheet API applies to standalone Vaktos. Review the product boundaries.
Frequently asked questions
Who can issue an API key?
An owner or admin can create one under Settings → API keys. The complete key is displayed once at creation; Vaktos retains a hash and visible prefix rather than the full credential.
Can the API write to Vaktos?
No. It is read-only. Authorised callers can retrieve hours, punches, shifts, period approval, leave and directory data, while planners continue to make changes inside Vaktos.
Which datasets are available?
The API exposes weekly or monthly timesheets, raw punches, approval periods, shifts including drafts, leave and the company directory. Timesheets include worked, paid, planned, overtime, evening, night, weekend and contract hours using the same calculation as the CSV and printable worksheet.
Can a key access another company?
No. The key itself determines the company scope; callers cannot supply a different company ID to redirect access.
What rate limits apply?
Each key allows 600 requests per minute, after which the API returns 429. Keys use a broad read scope rather than endpoint-level permissions. Revocation takes effect immediately. Punch and shift timestamps use UTC, while timesheet periods use local dates in the organisation’s timezone.