The roster actions read and write rostered shifts. get_roster returns the shifts for up to 31 days. add_roster replaces the shifts for the dates and Locations you send, so your software can keep part or all of a Microkeeper roster in step with its own.

Actions	`get_roster`, `add_roster`
Business key access	Roster: Read Only to get, Read/Write to add

This guide covers how to:

Get the roster.
Send a roster.

Before you start, make your keys and test your connection: see Microkeeper API. You'll need the Location IDs from API Locations, and the Job and Role IDs from API Jobs and API Roles.

Get the roster with get_roster

Send a date range of up to 31 days:

Field	Value
`mk_action`	`get_roster`
`mk_data`	`{"start_date":"2026-06-01","end_date":"2026-06-07"}`

Response

{
  "success": "1",
  "authenticated": "1",
  "message": "Roster data",
  "data": {
    "roster": [
      {
        "date": "2026-06-01",
        "LID": "14227",
        "ROID": "681",
        "JID": "0",
        "eusername": "william_smith",
        "EID": "53466",
        "start": "17:00:00",
        "end": "22:00:00",
        "break": "00:00:00",
        "hide": "0",
        "note": "",
        "checked": "0"
      }
    ]
  }
}

Every shift at an active Location is returned, for all staff:

Field	What it is
`date`	The day the shift starts, `YYYY-MM-DD`
`LID`	The shift's Location ID
`ROID`	The shift's Role ID, or `0`
`JID`	The shift's Job ID. If the shift has none, the Role's default Job, then the Location's. `0` if none of them has one
`eusername`, `EID`	The employee rostered. An open shift has a blank `eusername` and `EID` `0`
`start`, `end`	Start and finish times, `HH:MM:SS`. A shift past midnight finishes on an earlier time, such as `23:00:00` to `03:00:00`
`break`	The break time stored with the shift, `HH:MM:SS`
`hide`	`"1"` if the shift is hidden from the employee
`note`	The shift's note
`checked`	The employee's answer: `"0"` not yet, `"1"` accepted, `"2"` declined

Errors

Missing field either start_date or end_date
start_date must be before or equal to end_date
A maximum of 31 days can be selected: split longer ranges into several requests.
No roster data between 2026-06-01 and 2026-06-07: there are no shifts in the range.

Send a roster with add_roster

add_roster deletes every shift in the date range at the Locations you list, then adds the shifts you send. Your software is the source of truth for those dates and Locations:

Send the whole roster for the range each time. A day in the range with no shifts sent is left empty, so a Monday-to-Sunday range with only Monday-to-Friday shifts clears the weekend.
Only the Locations in config.LID change. Other Locations, such as ones your team rosters in Microkeeper, are left as they are.
To change or remove a shift, send the range again without it, or with it changed.

Example

{
  "config": {
    "method": "replace",
    "start_date": "2026-12-07",
    "end_date": "2026-12-13",
    "LID": [14227]
  },
  "shifts": [
    {
      "eusername": "ava_patel",
      "LID": 14227,
      "date": "2026-12-07",
      "start": "17:00",
      "end": "21:00",
      "JID": 1100,
      "note": "Booked by the rostering partner"
    },
    {
      "EID": 0,
      "LID": 14227,
      "date": "2026-12-11",
      "start": "23:00",
      "end": "03:00"
    }
  ]
}

The second shift is an open shift that finishes at 3 am the next day.

config fields

Field	Required	What it is
`method`	Yes	`replace`
`start_date`, `end_date`	Yes	The dates to replace, `YYYY-MM-DD`, up to 31 days
`LID`	Yes	A list of the Location IDs to replace, such as `[14227, 14228]`

shifts fields

Field	Required	What it is
`eusername` or `EID`	One of them	The employee. Send `EID` `0` or a blank `eusername` for an open shift. If both are sent, `EID` is used
`LID`	Yes	The Location ID. It must be in `config.LID`
`date`	Yes	The day the shift starts, `YYYY-MM-DD`, inside the range
`start`, `end`	Yes	`HH:MM` or `HH:MM:SS`. For a shift past midnight, send the finish as the time on the next day, such as `03:00`. A shift can be up to 23 hours 59 minutes
`JID`	No	The Job ID
`break`	No	A break time to store with the shift, `HH:MM:SS`. Defaults to `00:00:00`
`hide`	No	`1` to hide the shift from the employee. Defaults to `0`
`note`	No	A note on the shift

Shifts are added in the order you send them. Check each employee and Job ID against get_employees and get_jobs before you send: a shift whose employee isn't found is added as an open shift.

Response

{ "success":"1", "authenticated":"1", "message":"Shifts successfully inserted", "data": { "count": 2 } }

count is the number of shifts added. Compare it with the number you sent.

Errors

An error stops the request, and nothing is changed. The line numbers count from 0.

Message	What to check
`config array not set`, `method, start_date or end_date fields not set`	`config` has `method`, `start_date` and `end_date`
`method must be set to replace`	`method` is `replace`
`LID is not set or not a list array`	`config.LID` is a list, such as `[14227]`
`A maximum of 31 days can be selected`	The range is 31 days or less
`shifts array not set`	`shifts` is a list
`Roster record missing EID or eusername on line 0`	Each shift has `EID` or `eusername`
`LID not included in LID replace array, LID 14228`	The shift's Location is in `config.LID`
`date 2026-12-14 could not be found line 0`	The date is `YYYY-MM-DD` and inside the range
`start or end field missing on line 0`	Each shift has `start` and `end`
`999999 LID not on record`, `999999 JID not on record`	The Location is active, and the Job exists

Guides

API Roster

Get the roster with get_roster

Response

Errors

Send a roster with add_roster

Example

config fields

shifts fields

Response

Errors