^
Login

API Roles

The get_roles action returns every Role in the account, active and inactive, with each Role's ID (ROID) and the skills staff need for it. Use the ROIDs when you send roster shifts, timesheets and pay lines.

Actionget_roles
Business key accessAccount: Read Only

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

Get the Roles

Send status set to all:

FieldValue
mk_actionget_roles
mk_data{"status":"all"}

Response

{
  "success": "1",
  "authenticated": "1",
  "message": "Roles data",
  "data": {
    "roles": [
      {
        "ROID": "681",
        "title": "Bar",
        "GID": "0",
        "JID": "0",
        "active": "1",
        "skill_list": [
          { "SMID": "275", "title": "Responsible Service of Alcohol (RSA)" }
        ]
      },
      {
        "ROID": "682",
        "title": "Duty Manager",
        "GID": "0",
        "JID": "0",
        "active": "1",
        "skill_list": []
      }
    ]
  }
}

Roles are listed by title. Each one has:

FieldWhat it is
ROIDThe Role's ID in Microkeeper
titleThe Role's name
GIDThe Group the Role is limited to, or 0 for everyone
JIDThe Role's default Job, or 0 for none
active"1" active, "0" inactive
skill_listThe skills the Role needs, each with its skill ID (SMID) and title. Empty if none

Errors

  • The status variable must be included: send status.
  • Roles API field status must be set to all: status must be all.
  • There are no roles in Microkeeper yet: the account has no Roles.

Add or change Roles

Roles are added and changed in Microkeeper, in Menu > Settings > General > Roles: see Roles. Read them again with get_roles to pick up changes.

B2