API Timesheet

The timesheet actions send worked shifts to Microkeeper and read them back. add_timesheet adds shifts from your software, such as a time clock or job app, ready for payroll. get_timesheet returns the shifts worked in up to 31 days, however they were clocked.

This guide covers how to:

1. Send shifts.
2. Choose how new shifts replace earlier ones.
3. Add breaks, higher duties and Extra Rules.
4. Get timesheets.

Before you start, make your keys and test your connection: see Microkeeper API.

Send shifts with add_timesheet

Each shift needs the employee, the date, and the clock on and off times. Shifts sent through the API are approved, and recorded with the clocking method 613, Entered via API.

Example

{
  "config": { "replace": "overlap" },
  "shifts": [
    {
      "eusername": "ava_patel",
      "date": "2026-12-07",
      "clockon": "17:00",
      "clockoff": "21:00",
      "LID": 14227,
      "ROID": 681,
      "break_duration": 30,
      "note": "Sent by the rostering partner"
    },
    {
      "EmployeeID": "MEL-F-012",
      "date": "2026-12-07",
      "clockon": "09:00",
      "clockoff": "17:30",
      "JID": "STK-2026",
      "job_title": "December Stocktake"
    }
  ]
}

shifts fields

Encode mk_data with your language's JSON encoder, and URL-encode it, so quotes, apostrophes and ampersands in notes arrive intact.

Response

{ "success":"1", "authenticated":"1", "message":"2 shifts added replacing 1 shifts", "data": {"added":2,"replaced":1} }

added is the number of shifts added: compare it with the number you sent. replaced is the number of earlier shifts the new ones replaced.

Errors

An error stops the request, and nothing is changed.

• Timesheet API - field shifts not set: send shifts as a list.
• EID, EmployeeID or eusername must be set and date, clockon and clockoff must be set to add a shift
• eusername: ava_pate could not be found, and the same for EID and EmployeeID.
• The date range exceeds the 31 day limit: 2026-11-01 to 2026-12-07: send shifts more than 31 days apart in separate requests.
• higher_duties: su9 is not a Higher Duties code, extra_rules: 5678 is not an Extra Rule set to Selected on the Timesheet: see below.

Choose how new shifts replace earlier ones

Set config.replace to decide which shifts already in Microkeeper are deleted when you send new ones. By default, only shifts added through the API are replaced, so shifts staff clocked in Microkeeper are kept.

With date_range, also send replace_start and replace_end, as YYYY-MM-DD. Shifts deleted in your software disappear from Microkeeper on the next sync, so it's the best choice for keeping a copy of your timesheets:

{ "config": { "replace": "date_range", "replace_start": "2026-12-07", "replace_end": "2026-12-13" }, "shifts": [ ... ] }

To replace shifts however they were clocked, such as when moving a business from one clocking system to another, add "method": "all" to config. Otherwise leave it out.

A replaced shift is deleted with any changes managers made to it in Microkeeper, and its higher duties and Extra Rules. Include them in the new shift.

Add breaks, higher duties and Extra Rules

Breaks: break_duration

Send the break in minutes. Microkeeper puts the shift on the Selectable Break Rule with the same duration, such as a 30 minute meal break. If no Break Rule matches, the shift has no break. Break Rules are in Menu > Settings > Payroll Rules > Break Rules: see Break Rules.

Higher duties: higher_duties

Send the Code of a Higher Duties rule to pay the shift at higher duties. Higher Duties rules are on the Higher Duties tab of Shift Rules, and need payroll version 9. One Code is used per shift.

Extra Rules: extra_rules

Send the IDs of Extra Rules that are selected on the timesheet, from the ID column in Menu > Settings > Payroll Rules > Extra Rules. For a rule selected with a quantity, add the quantity after @: "9012@50" is 50 of rule 9012. Send an ID twice to apply the rule twice. Extra Rules need payroll version 9.

Get timesheets with get_timesheet

Send a date range of up to 31 days. To get some staff only, add eusername or EID, with several separated by commas:

Response

{
  "success": "1",
  "authenticated": "1",
  "message": "Timesheet data",
  "data": {
    "timesheet": [
      {
        "TSID": "256817",
        "eusername": "ava_patel",
        "EID": "53613",
        "date": "2026-06-01",
        "clockon": "17:00:00",
        "clockoff": "21:00:00",
        "original_on": "17:00:00",
        "original_off": "21:00:00",
        "mod_on": "",
        "mod_off": "",
        "LID": "14227",
        "ROID": "681",
        "JID": "0",
        "note": "",
        "break_min": 0,
        "paid_hours": 4,
        "method_on": "610",
        "method_off": "610",
        "approved": "1",
        "who_approved": "auto",
        "higher_duties": [],
        "extra_rules": []
      }
    ]
  }
}

Every shift in the range is returned, approved or not, by date, employee and clock on time:

Breaks are worked out on each shift alone. Payroll joins back-to-back shifts, such as 10:00 to 12:00 then 12:00 to 15:00, into one 5-hour shift for breaks, so its totals can differ.

Clocking methods

Errors

• Missing field either start_date or end_date
• start_date must be before or equal to end_date
• The date range exceeds the 31 day limit: 2026-06-01 to 2026-07-31: split longer ranges into several requests.
• There is no timesheet data for this period: no shifts match the range and staff.