Add, update and get employee via developer API

This guide explains how to add, update or get employee data via Microkeeper developer API.

Adding 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

Variable name	Value - Minimum requirement
mk_action	add_employees
mk_data	{ "Employees":[{"firstname":"John", "lastname":"Smith"}] }

Step 3

List of available fields

The minimum fields required to add a new employee to Microkeeper are the first name and last name, if missing no employees will be added.

Here is a full list of variables that can be added to mk_data to fill an employees profile.

If a field is missing a default or blank value will be set.

If an unknown format is supplier, the employees profile will still be created, but that field will be missing and no error will be displayed.

Verify the data has been passed successfully by inspecting the employee profile in Microkeeper.

Variable name	Description	Formats	Example	Addable	Updatable	Getable
EID	Employee ID in Microkeeper Unique identifier	Integer	12345	No	No (1)	Yes
eusername	Employee username Unique identifier	Standardised "firstname_lastnameX" Read auto_username	John_smith	No, but can be automatically generated	No (1)	Yes
EmployeeID	Employee ID in 3rd party system Unique identifier	Alphanumeric Must be set to "blank" or Unique	emp_001	Yes	No (1)	Yes
(1) Any of the following can be used as a unique identifier to update the employee: EID, eusername, EmployeeID
firstname	Given name	Alpha	John	Yes	No	Yes
lastname	Surname	Alpha	Smith	Yes	No	Yes
email	Email	Email	update@me.com	Yes	Yes Verification required	Yes
phoneno	Mobile number	Numeric	0401 321 321	Yes	Yes Verification required	Yes
home_no	Home number	Numeric	03 5211 2233	Yes	Yes	Yes
kin_name	Next of kin name	Alpha	Roger	Yes	Yes	Yes
kin_no	Next of kin phone number	Numeric	03 5244 0011	Yes	Yes	Yes
address	Address line 1	Alphanumeric	Unit 2	Yes	Yes	Yes
address2	Address line 2	Alphanumeric	1 Smith St	Yes	Yes	Yes
city	Suburb	Alpha	Belmont	Yes	Yes	Yes
state	State (OTH for overseas)	VIC,NSW,NT,QLD,SA,TAS,WA,OTH	VIC	Yes	Yes	Yes
timezone	Time zone	Australia/Victoria etc If missing will default to state	Australia/Victoria	Yes	Yes	Yes
postcode	Postcode	Numeric	3216	Yes	Yes	Yes
country	Country	Alpha	Australia	Yes	Yes	Yes
dob2	Date of birth	dd/mm/yyyy or yyyy-mm-dd	1970-11-23	Yes	No - Used as a security checkpoint	Yes
startdate2	Start date	dd/mm/yyyy or yyyy-mm-dd	2014-10-20	Yes	Yes	Yes
terdate2	Termination date	dd/mm/yyyy or yyyy-mm-dd	2014-10-20	Yes	Yes	Yes
cessation_type	Cessation Type	String of max length 1: "" = Blank (default) V = Voluntary I = Ill Health D = Deceased R = Redundancy F = Dismissal C = Contract T = Transfer	V	Yes	Yes	Yes
last_modified	Date the record was last modified	yyyy-mm-dd	2018-11-22	No will default to today	No, will be updated by Microkeeper	Yes
sex	Gender	String will accept: F,Female,1 M,Male,2 I,Indeterminate O,Other	M	Yes	Yes	Yes as bold option
rate	Pay rate	Decimal - Dollar value	16.1943	Yes	Yes	Yes
RRNID	Rate Rule Name ID	Integer	1234	Yes	Yes	Yes
tax	Tax scale	Integer 1 = Australian Resident 5 = Foreign Resident 8 = Working holiday makers 4 = Sub-Contractor	1	Yes	Yes	Yes
employment_override	Status Override	String of max length 1: "" = Blank, use Status (Default) D = Death Beneficiary L = Labour Hire N = Non-Employee V = Voluntary Agreement	D	Yes	Yes	Yes
income_type	STP Income Stream Type	String of max length 3: "" = SAW (Default) CHP = Closely Held Payees IAA = Inbound Assignees to Australia WHM = Working Holiday Maker SWP = Seasonal Worker Programme VOL = Voluntary Agreement LAB = Labor Hire OSP = Other Specified Payments FEI = Foreign Employment	WHM	Yes	Yes	Yes
tax_free	Tax Free Threshold Claimed	Boolean	1	Yes	Yes	Yes
help	HELP PAYG tax	Boolean	0	Yes	Yes	Yes
tsl	Trade Support Loan	Boolean	0	Yes	Yes	Yes
sfss	Student Financial Supplement Scheme	Boolean	0	Yes	Yes	Yes
senior_tax	Seniors and Pensioners Tax Offset	Boolean	0	Yes	Yes	Yes
tax_per	Fixed Tax percentage	Integer - Percentage	20	Yes	Yes	Yes
tax_add	Tax offset	-1000 to +1000 - Dollar value	50	Yes	Yes	Yes
etfn	Tax File Number	Numeric	321 321 321	Yes	No	No, due to the sensitive nature of TFNs they can not be exported The export will include either "not_set" or "set" instead.
superbasic	Super on Basic hours or Basic and Overtime	String: TRUE = OTE only FALSE = OTE and OT	0 = default	Yes	No	Yes
super_fix_type	Fixed, will override the super value Minimum, super value no less than Maximum, super value no greater than	Integer: 0 = Fixed 1 = Minimum 2 = Maximum	0 = default, feature disabled 100	Yes	No	Yes
super_fixed	Fixed, min or max amount of super_fix_type	Decimal	155.55	Yes	No	Yes
super_fund	Super Fund	String USI / SPIN / Fund Name A search is made to try and find a match, if found the ID of the fund will be set, if a unique match can not be found this will need to be manually corrected.	82004832237178 or RES0101AU or REST	Yes	Yes	Yes refer to super_fund array
super_no super_no_2 super_no_3 super_no_4	Super Member Number	Alphanumeric	655655655	Yes	Yes	Yes
super_fund_2 super_fund_3 super_fund_4	= Additional employer super = Salary Sacrifice = After tax contribution	Yes refer to super_fund array	Yes refer to super_fund array	No	No	Yes refer to super_fund array
basichours	Basic hours	Decimal - Hours	38	Yes	No	Yes
salary	Salary	String of max length 1: T=True F=False	T	Yes	No	Yes
status	Employment status	Full Time,F,f,FT,FULLTIME Casual,C,c,CA,CASUAL Part Time,P,p,PT,PARTTIME Sub-Contractor Subby-Super	Full Time	Yes	No	Yes as bold option
abn	Sub-Contractor ABN Only used if status is set to Sub-Contractor	Integer	82004832237	Yes	Yes	Yes
businessname	Sub-Contractor Business Name Only used if status is set to Sub-Contractor	String	ABC Contractor Pty Ltd	Yes	Yes	Yes
active	Active or Terminated	String of max length 5: TRUE = TRUE FALSE = FALSE	TRUE	No, employee will be active when first added	Yes	Yes
entitledal	Entitled annual leave weeks	Decimal - Weeks	4	Yes	Yes	Yes
rdo	Rostered day off hours deducted	Integer - Hours	2	Yes	Yes	Yes
leaveloading	Annual leave loading	Decimal - Percentage	17.5	Yes	Yes	Yes
entitledsickleave	Entitled personal leave	Decimal - Weeks	2	Yes	Yes	Yes
entitled_long	Entitled long service leave	Decimal - 1 week in x	60	Yes	No	Yes
preyear	The year Pre-accumulated data is applied to	Year 2020 = 2020/2021 Default = Current fiscal year	2020	Yes	No	Yes
preacal	Pre-accumulated annual leave	Decimal - Hours	123.32	Yes	No	Yes
pre_long	Pre-accumulated long service leave	Decimal - Hours	123.32	Yes	No	Yes
pre_sick	Pre-accumulated personal leave	Decimal - Hours	123.32	Yes	No	Yes
prerdo	Pre-accumulated RDO	Decimal - Hours	123.32	Yes	No	Yes
prenet	Pre-accumulated net	Decimal - Dollar	10000.22	Yes	No	Yes
presuper	Pre-accumulated super above 9.5	Decimal - Dollar	10000.22	Yes	No	Yes
pretax	Pre-accumulated tax	Decimal - Dollar	10000.22	Yes	No	Yes
pregross	Pre-accumulated gross	Decimal - Dollar	10000.22	Yes	No	Yes
eTitle	Bank title account 1	String	Mr John Smith	Yes	Yes	Yes
eBSB_A	Bank BSB account 1	xxx-xxx or xxxxxx or xxxxx	011-222	Yes	Yes	Yes
eAccountNo	Bank account no account 1	Numeric	123123123	Yes	Yes	Yes
split_pay	Split pay to account 2	String of max length 3: "" = Blank,NA fix = Fix amount per = Percentage	fix	Yes	No	Yes
split_amount	Split amount to account 2	Decimal - Percentage or Amount	200	Yes	No	Yes
eTitle2	Bank title account 2	String	Mr John Smith	Yes	No	Yes
eBSB_B	Bank BSB account 2	xxx-xxx or xxxxxx or xxxxx	011-222	Yes	No	Yes
eAccountNo2	Bank account number account 2	Numeric	111222333	Yes	No	Yes
split_pay3	Split pay to account 3	String of max length 3: "" = Blank,NA fix = Fix amount per = Percentage	nul	Yes	No	Yes
split_amount3	Split amount to account 3	Decimal - Percentage or Amount	0	Yes	No	Yes
eTitle3	Bank title account 3	String		Yes	No	Yes
eBSB_C	Bank BSB account 3	xxx-xxx or xxxxxx or xxxxx	011-222 or 011222 or 11222	Yes	No	Yes
eAccountNo3	Bank account number account 3	Numeric		Yes	No	Yes
default_LID	Default Location	Integer	7656	Yes	Yes	Yes
default_ROID	Default Role	Integer	2343	Yes	Yes	Yes
default_job	Default Job Can be found by mousing over ID in Job list	Integer	1234	Yes	No	Yes
primary_manager	Username of primary manager	String	john_smith	Yes	No	Yes
position	Position of employee	String	CFO	Yes	No	Yes
show_sick	Show the employees Personal Leave balance on the Payslip	Boolean	1	Yes	Yes	Yes
show_annu	Show the employees Annual Leave balance on the Payslip	Boolean	1	Yes	Yes	Yes
show_long	Show the employees LSL balance on the Payslip	Boolean	1	Yes	Yes	Yes
show_rdo	Show the employees RDO/TIL balance on the Payslip	Boolean	1	Yes	Yes	Yes
duplicate_check	Checks if a user already exists via email	String=email	email	Yes	NA	NA
auto_username	Forces a username to be created in the format firstname_lastnameX X is incremented until a unique username is found	Boolean 1 0	1	Yes	NA	NA
welcome	Sends out welcome message via email and/or SMS auto_username must be true	String with 3 options: sms email both If omitted no welcome message will be sent	sms	Yes	NA	NA
custom_{ID}	Custom fields created and managed by the employer. example custom_favourite_pizza	String	Hawaiian Pizza	Yes	Yes	Yes

Custom Fields

Custom fields can be created by the business, they will be in the format of "custom_{ID}" example "custom_favourite_pizza"

There can be an unlimited number of custom fields.

Archived fields will not be included.

If there is no data for the field it will still be present it will just be blank.

auto_username must be true to add staff via API

Step 4

Response

The response will be in JSON and in the format outlined in the Hello World example.

When the employee is added to the Microkeeper database an EID (Employee ID) is created, the EID is included in the JSON response.

If you pass your EmployeeID this will be returned in the response from Microkeeper.

If a duplicate is detected the response will also include a list of duplicates by email to the related EmployeeID if set.

Successful example

{ "success":"1", "authenticated":"1", "message":"2 staff added to Microkeeper", "data":{"EID":{"55555":68782,"55556":68783}} }

Successful example with duplicate detected

{ "success":"1", "authenticated":"1", "message":"1 staff added to Microkeeper", "data": {"EID":{"5555":18776},"duplicate":{"5556":"test@test.com"}} }

Updating Employees via API

Step 1

Set the mk_action variable and mk_data variable

Variable name	Value - Minimum requirement
mk_action	update_employees
mk_data	{ "Employees":[{"EID":"3","EmployeeID":"5555","eAccountNo":"111"},{"eusername":"joel_davis","EmployeeID":"5556", "phoneno":"040155522"}] }

The format for updating an Employee is very similar to the format for adding an employee, with a few key difference.

The field EID, eusername or EmployeeID must be included so Microkeeper knows which employee to update
Not all fields can be updated, only commonly changed fields are recorded
Only fields that are supplied are updated
Refer to add employee table above to see which fields are updatable

Updating email and mobile number

Microkeeper requires an employee to verify their mobile number and email address.

If the field email or phoneno is supplied Microkeeper will reset the verification field and the employee will be required to verify again.

Response

Step 2

When the employee is updated in the Microkeeper database the EID (Employee ID) is included in the JSON response.

If you pass your EmployeeID this will be returned in the response from Microkeeper.

Successful example

{ "success":"1", "authenticated":"1", "message":"2 staff updated in Microkeeper", "data":{"EID":{"5555":3,"5556":68783}} }

Get Employee data via API

Via last_modified

Employee data can be retrieve via API based on the last_modified field, this field can be set up to 365 days in the past or can be set to "active".

If you intend on storing a copy of the data, we recommend the date option and hitting the API at a set interval, for example every 7 days where the last_modified field was set 7 days ago.

If you do not intend on storing the data, we recommend setting the last_modified field to "active", which will only return active staff.

Via user_list

Alternative employee data can be retrieved by supplying a user_list of user.

Either via EmployeeID, EID or eusername can be supplied, example payloads below.

This should be used for getting small batches of users.

If you need to retrieve batching of users over 100 we would suggest using the last_modified option.

Step 1

Set the mk_action variable and mk_data variable.

Variable name

Values and Example

mk_action

get_employees

mk_data

{"config":{"last_modified":"2018-10-20"}

{"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 table above for exported formats

super_fund array

Variable name	Description	Output format	Example
SFID	Super Fund ID	Integer	111
name	The common name of the fund.	String	AMP Personal Super Plan
ABN	Australia Business Number of Super Fund This is not always recorded unless a SMSF is selected	Number	76514770399
USI	Unique Super Identifier Recommended to identify a fund Not recorded for SMSF	Alphanumeric	76514770399003
spin	Superannuation Product Identification Number This should not be used as two different funds can share the same number	Alphanumeric	AMP0278AU

groups array

Variable name	Description	Output format	Example
GID	Group ID as recorded in Microkeeper If record present employee is in this group	Integer	111
per	Percentage for cost centre tracking Between 0 - 100	Decimal	100

Response

Step 3

The format will be in JSON as outlined in the Hello World example.

A successful response might include no employees, thus a message will be returned "No employees have been updated since 21/12/2018" thus the system should be tested for this scenario.

The data field will include an employees field, ref to example below.

Successful example

{ "success":"1", "authenticated":"1", "message":"2 staff retrieved from Microkeeper", "data":{"employees":[{"EID":"3","eusername":"john_smith","firstname":"John","lastname":"Smith","email":"test@test.com","phoneno":"0401635555","home_no":"","kin_name":"John Smith","kin_no":"0438594444","address":"1 Smith Street","address2":"","city":"Ravenswood","state":"TAS","timezone":"Australia\/Victoria","postcode":"7250","country":"Australia","dob2":"1986-05-06","startdate2":"2016-11-01","terdate2":"0000-00-00","last_modified":"2018-11-22","sex":"M","rate":"30","tax":"1","help":"0","tax_free":"0","tsl":"0","sfss":"0","senior_tax":"0","tax_dec_date":"2018-03-09","tax_per":"0","tax_add":"0","etfn":"set","basichours":"38","salary":"F","status":"Part Time" ,"abn":"82004832237" ,"businessname":"ABC Contractor Pty Ltd" ,"active":"TRUE","entitledal":"4","rdo":"0","leaveloading":"17.5","entitledsickleave":"2","entitled_long":"60","preacal":"0","pre_long":"0","pre_sick":"0","prerdo":"0","prenet":"0.00","presuper":"0.00","pretax":"0.00","pregross":"14226.33","super_per":"0","super_fixed":"0.00","super_fund":{"SFID":"482","name":"REST Employer Sponsored Division","ABN":"","USI":"RES0103AU","spin":"RES0103AU"},"super_no":"111111","super_fund_2":{"SFID":"712","name":"Amp endowment personal super plan","ABN":"76514770399","USI":"76514770399003","spin":""},"super_no_2":"111112","super_fund_3":{"SFID":"46","name":"AMP SuperLeader Plan","ABN":"","USI":"AMP0278AU","spin":"AMP0278AU"},"super_no_3":"111113","super_fund_4":{"SFID":"672","name":"Kingston superannuation trust","ABN":"44189308050","USI":"44189308050001","spin":""},"super_no_4":"111114","eTitle":"hgfd","eBSB":"063-504","eAccountNo":"123456789","split_pay":"fix","split_amount":"20.00","eTitle2":"Mr Joel Davis2","eBSB2":"222-222","eAccountNo2":"2222","split_pay3":"fix","split_amount3":"33.00","eTitle3":"Mr John Smith","eBSB3":"066-333","eAccountNo3":"33333","default_job":"909","position":"CEO","groups":[{"GID":"1703","per":"100"},{"GID":"1630","per":"100"},{"GID":"1425","per":"100"},{"GID":"1295","per":"100"},{"GID":"1702","per":"100"},{"GID":"1296","per":"100"}]}]} }

Same Example Readable

{
  "success": "1",
  "authenticated": "1",
  "message": "2 staff retrieved from Microkeeper",
  "data": {
    "employees": [
      {
        "EID": "3",
        "eusername": "john_smith",
        "firstname": "John",
        "lastname": "Smith",
        "email": "test@test.com",
        "phoneno": "0401635555",
        "home_no": "",
        "kin_name": "John Smith",
        "kin_no": "0438594444",
        "address": "1 Smith Street",
        "address2": "",
        "city": "Ravenswood",
        "state": "TAS",
        "timezone": "Australia/Victoria",
        "postcode": "7250",
        "country": "Australia",
        "dob2": "1986-05-06",
        "startdate2": "2016-11-01",
        "terdate2": "0000-00-00",
        "last_modified": "2018-11-22",
        "sex": "M",
        "rate": "30",
        "tax": "1",
        "help": "0",
        "tax_free": "0",
        "tsl": "0",
        "sfss": "0",
        "senior_tax": "0",
        "tax_dec_date": "2018-03-09",
        "tax_per": "0",
        "tax_add": "0",
        "etfn": "set",
        "basichours": "38",
        "salary": "F",
        "status": "Part Time",
        "abn": "82004832237",
        "businessname": "ABC Contractor Pty Ltd",
        "active": "TRUE",
        "entitledal": "4",
        "rdo": "0",
        "leaveloading": "17.5",
        "entitledsickleave": "2",
        "entitled_long": "60",
        "preacal": "0",
        "pre_long": "0",
        "pre_sick": "0",
        "prerdo": "0",
        "prenet": "0.00",
        "presuper": "0.00",
        "pretax": "0.00",
        "pregross": "14226.33",
        "super_per": "0",
        "super_fixed": "0.00",
        "super_fund": {
          "SFID": "482",
          "name": "REST Employer Sponsored Division",
          "ABN": "",
          "USI": "RES0103AU",
          "spin": "RES0103AU"
        },
        "super_no": "111111",
        "super_fund_2": {
          "SFID": "712",
          "name": "Amp endowment personal super plan",
          "ABN": "76514770399",
          "USI": "76514770399003",
          "spin": ""
        },
        "super_no_2": "111112",
        "super_fund_3": {
          "SFID": "46",
          "name": "AMP SuperLeader Plan",
          "ABN": "",
          "USI": "AMP0278AU",
          "spin": "AMP0278AU"
        },
        "super_no_3": "111113",
        "super_fund_4": {
          "SFID": "672",
          "name": "Kingston superannuation trust",
          "ABN": "44189308050",
          "USI": "44189308050001",
          "spin": ""
        },
        "super_no_4": "111114",
        "eTitle": "hgfd",
        "eBSB": "063-504",
        "eAccountNo": "123456789",
        "split_pay": "fix",
        "split_amount": "20.00",
        "eTitle2": "Mr Joel Davis2",
        "eBSB2": "222-222",
        "eAccountNo2": "2222",
        "split_pay3": "fix",
        "split_amount3": "33.00",
        "eTitle3": "Mr John Smith",
        "eBSB3": "066-333",
        "eAccountNo3": "33333",
        "default_LID": "321",
        "default_ROID": "543",
        "default_job": "909",
        "position": "CEO",
        "groups": [
          {
            "GID": "1703",
            "per": "100"
          },
          {
            "GID": "1630",
            "per": "100"
          },
          {
            "GID": "1425",
            "per": "100"
          },
          {
            "GID": "1295",
            "per": "100"
          },
          {
            "GID": "1702",
            "per": "100"
          },
          {
            "GID": "1296",
            "per": "100"
          }
        ]
      }
    ]
  }
}

Guides

Add, update and get employee via developer API

Adding Employees via API

Custom Fields

Response

Updating Employees via API

Updating email and mobile number

Response

Get Employee data via API

Via last_modified

Via user_list

Review data standards

super_fund array

groups array

Response