API Employee

The Employee actions keep staff in step between your software and Microkeeper. upsert_employees adds new staff and updates existing ones. get_employees returns staff profiles, either everyone changed since a date or the staff you name. get_group_config lists the account's Groups.

This guide covers how to:

1. Identify staff.
2. Add and update staff.
3. Get staff profiles.
4. Get the Groups.

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

How staff are identified

Each employee has three IDs:

Use EmployeeID to keep staff in step: it's the only one you choose, and the only way to add staff through the API. It's up to 20 characters, and unique in the business.

For staff already in Microkeeper, ask the business to fill in each employee's Employee ID in their profile before your first sync, or match them by eusername. A request with an EmployeeID Microkeeper hasn't seen adds a new employee, even when its eusername matches someone.

Add and update staff with upsert_employees

Send a list of staff in Employees. Each one is matched in this order:

1. EmployeeID: a known one updates that employee; a new one adds an employee.
2. eusername: updates that employee.
3. EID: updates that employee.

Every employee needs firstname and lastname, updates included. Each ID can appear only once in a request.

Example

{
  "Employees": [
    {
      "EmployeeID": "MEL-C-031",
      "firstname": "Noah",
      "lastname": "Reid",
      "email": "noah.reid@outlook.com",
      "phoneno": "0491570160",
      "startdate2": "2026-12-01",
      "status": "Casual",
      "rate": "30",
      "super_fund": "STA0100AU",
      "eBSB_A": "062-000",
      "eAccountNo": "10000031",
      "custom_emergency_contact": "Mia Reid",
      "welcome": "email"
    },
    {
      "EmployeeID": "MEL-F-012",
      "firstname": "Amelia",
      "lastname": "Brown",
      "address": "14 Smith Street",
      "city": "Fitzroy",
      "state": "VIC",
      "postcode": "3065"
    }
  ]
}

Noah is added and sent a welcome email. Amelia's address is updated.

Response

{
  "success": "1",
  "authenticated": "1",
  "message": "User added or updated to Microkeeper",
  "data": {
    "added": { "EID": { "MEL-C-031": "55572" } },
    "updated": { "EID": { "MEL-F-012": "53529" } }
  }
}

added and updated give each employee's EID, keyed by the EmployeeID you sent. Staff matched by eusername or EID are listed as "updated":{"EID":["53613"]}. Each list is there only when it has something in it.

Adding staff

A new employee's username is made from their name, such as noah_reid, with a number added if it's taken. Find it in get_employees. New staff are active, and added to any Groups set to add new staff automatically.

To send the employee their login, add welcome: email, sms or both.

Fields you leave out take Microkeeper's defaults, such as Full Time status and the account's leave entitlements for that status. After adding staff, ask the business to check their profiles in Microkeeper before their first pay run.

Updating staff

An update changes only the fields you send, from the Update column below. Send dates as YYYY-MM-DD.

Name, date of birth, status, pay type, basic hours, default Location and Role, position and super options are set when the employee is added. To change them later, the business changes them in the employee's profile in Microkeeper.

Changing email or phoneno asks the employee to verify the new one.

Fields

Custom fields

Send the business's custom fields as custom_ followed by the field's name, as get_employees returns it. Send dates as YYYY-MM-DD. Archived custom fields, and names that don't match, are skipped.

Opening balances: open_balance

Set the hours or amounts an employee starts with, by financial year:

"open_balance": { "2026": { "al": 80, "sick": 40, "pregross": 25000 } }

Other leave types: leave_quota

For leave types the business has added, set how much the employee accrues, and whether the balance shows on payslips:

"leave_quota": { "stud": { "accrual_amount": 1, "payslip_hide": 0 } }

Annual, personal, long service and RDO entitlements use the leave fields above instead.

Errors

An error stops the request, and no staff are changed:

• JSON missing Employees field
• JSON missing firstname or lastname field: every employee needs both.
• EmployeeID is present twice in payload: MEL-C-031, and the same for EID and eusername.
• eusername must be present in Microkeeper: noah_red, EID must be present in Microkeeper: 99999: to add someone, send an EmployeeID.
• A unique ID must be supplied either: EmployeeID, EID or eusername
• No employees added or updated in Microkeeper: nothing in the request changed anyone.

Get staff with get_employees

Ask for staff changed since a date, all active staff, or the staff you name:

To keep a copy of the business's staff, get active once, then the staff changed since your last sync. An employee's last_modified is the date their profile last changed, in Microkeeper or through the API.

Response

{
  "success": "1",
  "authenticated": "1",
  "message": "1 staff retrieved from Microkeeper",
  "data": {
    "employees": [
      {
        "EID": "53613",
        "EmployeeID": "",
        "eusername": "ava_patel",
        "firstname": "Ava",
        "lastname": "Patel",
        "email": "ava.patel@outlook.com",
        "phoneno": "0491570156",
        "startdate2": "2026-06-01",
        "terdate2": "0000-00-00",
        "last_modified": "2026-10-20",
        "rate": "32",
        "status": "Casual",
        "active": "TRUE",
        "etfn": "set",
        "super_fund": { "SFID": "8", "name": "AustralianSuper", "ABN": "65714394898", "USI": "STA0100AU", "spin": "STA0100AU" },
        "super_no": "500000001",
        "eBSB": "062-000",
        "eAccountNo": "10000001",
        "groups": [ { "GID": "59467", "per": "100" }, { "GID": "59462", "per": "100" } ],
        "open_balance": 0,
        "leave_quota": 0,
        "custom_emergency_contact": "Sam Patel",
        "...": "..."
      }
    ]
  }
}

Staff are listed by username, with the fields above and a few more. These come back differently from how you send them:

• etfn is set or not_set. The tax file number itself is never returned.
• BSBs are eBSB, eBSB2 and eBSB3.
• super_fund is the fund's SFID, name, ABN, USI and spin, or 0 if none is set. A self-managed fund has no USI: use its ABN.
• groups lists each Group's GID and the percentage of the employee's cost it carries (per), or is 0.
• open_balance and leave_quota have the shapes above, or are 0.
• Custom fields are all listed, blank if not filled in. Dates are YYYY-MM-DD.

Messages

• No employees have been updated: no staff match. The response has "success":"1" and no data.
• last_modified must be within the last year
• EmployeeID is not object list or empty, and the same for EID and eusername: send a list with at least one ID.
• config missing last_modified or user_list field

Get the Groups with get_group_config

Groups organise staff for rosters, access, pay cycles and reports. Use their GIDs to read the groups on each employee.

Response

{
  "success": "1",
  "authenticated": "1",
  "message": "2 groups retrieved from Microkeeper",
  "data": {
    "groups": [
      { "GID": 59467, "name": "Melbourne Staff", "auto_add": 0, "access": 0, "access_name": "All", "hide": 0 },
      { "GID": 59462, "name": "Melbourne Weekly", "auto_add": 0, "access": 4, "access_name": "Pay Cycle", "hide": 0 }
    ]
  }
}