Upsert and get employee via developer API

This guide explains how to upsert (insert-or-update) and get employee data via the Microkeeper developer API.

Upserting Employees via API

Step 1

Before starting this tutorial make sure you have completed the Hello World tutorial.

Complete the hello_world tutorial Hello World

Step 2

Set the mk_action variable and mk_data variable.

{ "Employees": [ { "EmployeeID":"emp_001", "firstname":"John", "lastname":"Smith", "email":"john@example.com", "phoneno":"0400123456", "super_fund":"RES0103AU", "welcome":"email" } ] }

Step 3

List of available fields (upsert)

The minimum fields required are firstname and lastname. For updates, include an identifier (EmployeeID, EID or eusername).

If a field is missing a default or blank value may be set. If an unknown format is supplied, the profile is still processed but that field may be skipped without error. Verify the data in the Microkeeper UI after upsert.

Many other fields remain supported as in the legacy table (banking accounts 2 & 3, super_fund_2..4, pre-accumulated fields, status, salary, etc.). Behaviour and formats are unchanged unless noted above.

Open Balance

These objects can be included per employee in upsert_employees to insert/update opening balances.

"open_balance": { "2024": { "al": 80, "sick": 16 }, "2025": { "al": 40 } }

Supported open_key keys are:

Leave Quota

This tool is to be used along side custom leave type, where the employer add new leave types outside of the supplied standard list so:

TOIL does not have a fixed accrual amount.

"leave_quota": { "toil": { "accrual_amount": 2.923, "payslip_hide": 0 }, "rdo": { "accrual_amount": 1.462 } }

Custom Fields

Custom fields are sent/returned as custom_{field}, e.g. custom_favourite_pizza.

• Only active custom fields are processed.
• Date-validated custom fields are exported as yyyy-mm-dd.
• Unlimited fields supported.

Step 4

Response

The response will be JSON.

When employees are added or updated, the response includes the list of EID for affected records. If you passed your EmployeeID, it will be echoed with its EID.

Successful example

{ "success":"1", "authenticated":"1", "message":"User added or updated to Microkeeper", "data":{ "added":{"emp_001":68783}, "updated":{"EID":[12345,12346]} } }

Notes: On updates that matched an existing record, email/phone re-verification flags are reset if email or phoneno changed.

If nothing was added or updated, an error message is returned.

Get Employee data via API

Via last_modified

You can retrieve staff by last_modified (up to 365 days back) or use "active" to return only active staff.

Via user_list

Alternatively, supply a user_list with EmployeeID, EID, or eusername arrays to fetch specific users.

Step 1

Set the mk_action and mk_data variables.

{"config":{"last_modified":"2025-10-01"}}

{"config":{"last_modified":"active"}}

{"config":{"user_list":{"EmployeeID":["abc1","abc2"]}}}

{"config":{"user_list":{"EID":["111","222"]}}}

{"config":{"user_list":{"eusername":["jane_d","john_s"]}}}

Step 2

Review data standards

Refer to the upsert table for exported formats.

Sensitive fields (e.g. TFN) are not exported; instead, etfn will be set or not_set.

super_fund array

groups array

open_balance object

leave_quota object

Response

Step 3

The format will be JSON.

A successful response might include no employees if no records matched your filters. The data field will include an employees array.

Successful example:

{
  "success": "1",
  "authenticated": "1",
  "message": "2 staff retrieved from Microkeeper",
  "data": {
    "employees": [
      {
        "EID": "3",
        "EmployeeID": "emp_001",
        "eusername": "john_smith",
        "firstname": "John",
        "lastname": "Smith",
        "...": "...",
        "super_fund": {
          "SFID": "482",
          "name": "REST Employer Sponsored Division",
          "ABN": "",
          "USI": "RES0103AU",
          "spin": "RES0103AU"
        },
        "groups": [
          { "GID": 111, "per": 100 }
        ],
        "open_balance": {
          "2024": { "al": 80, "sick": 16 }
          "2025": { "sick": 80, "sick": 16 }
        },
        "leave_quota": {
          "al": { "accrual_amount": 2.923, "payslip_hide": 0 }
        }
      }
    ]
  }
}

Updating email and mobile number

If email or phoneno is updated, Microkeeper will reset the verification flags and the employee will need to verify again.