^

Guides

Getting Started
  Introduction
  Your Business Settings
  Export From Other Systems
  Add An Employee
  Clocking Hours
  Timesheet Software
  Grouping Employees
  Management Configuration
  Locations

Rostering
  The Roster Process
  Roster Templates
  Roster Calendar
  Calendar View
  SMS Rosters

Timesheets
  The Timesheet Process
  Timesheet vs Roster
  Timesheet from Roster

Payroll
  The Payroll Process
  A Payrun
  Rate Rules
  Shift Rules
  Break Rules
  Deduction Rules
  Extra Rules
  Time In Lieu
  Public Holidays
  Jobs and Cost Centres

HR
  The Leave Request Process
  Leave Request Review
  Leave Payroll Process
  Skills Matrix

Reports
  Reports
  Single Touch Payroll
  Payment Summary
  Xero Integration

Other features
  Messaging

SuperChoice
  Processing Super

SuperChoice (Old process)
  Super Clearing House
  SuperChoice Setup
  Adding Super Fund
  Adding Employees
  Super Payment

Employees
  Employee Console
  Smartphone Login
  Push Notification
  Requesting Leave

Developers
  Partner Logo
  API Hello World
  API Employee
  API Timesheet
  API Payroll
  API Jobs
  API Roster

  Print Guide

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 nameValue - 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

AddableUpdatableGetable
EID
Employee ID in Microkeeper

Unique identifier

Integer
NoNo, required to update or eusernameYes
eusername
Employee username

Unique identifier

Standardised
"firstname_lastnameX"

Read auto_username


No, but can be automatically generated

No, required to update or EIDYes

firstname

Given name

Alpha

John

YesNoYes

lastname

Surname

Alpha

Smith

YesNoYes

email

Email

Email

update@me.com

YesYes
Verification required
Yes

phoneno

Mobile number

Numeric

0401 321 321

YesYes
Verification required
Yes

home_no

Home number

Numeric

03 5211 2233

YesYesYes

kin_name

Next of kin name

Alpha

Roger

YesYesYes

kin_no

Next of kin phone number

Numeric

03 5244 0011

YesYesYes

address

Address line 1

Alphanumeric

Unit 2

YesYesYes

address2

Address line 2

Alphanumeric

1 Smith St

YesYesYes

city

Suburb

Alpha

Belmont

YesYesYes

state

State (OTH for overseas)

VIC,NSW,NT,QLD,SA,TAS,WA,OTH

VIC

YesYesYes

timezone

Time zone

Australia/Victoria etc

If missing will default to state

Australia/Victoria

YesYesYes

postcode

Postcode

Numeric

3216

YesYesYes

country

Country

Alpha

Australia

YesYesYes

dob2

Date of birth

dd/mm/yyyy or yyyy-mm-dd

1970-11-23

YesNoYes

startdate2

Hire date

dd/mm/yyyy or yyyy-mm-dd

2014-10-20

YesNoYes

terdate2

Termination date

dd/mm/yyyy or yyyy-mm-dd

2014-10-20

YesYesYes

last_modified

Date the record was last modifiedyyyy-mm-dd2018-11-22No will default to todayNo, will be updated by MicrokeeperYes

sex

Gender

F,Female,1

M,Male,2

M

YesNoYes as bold option

rate

Pay rate

Decimal - Dollar value

16.1943

YesYesYes

tax

Tax scale

1 = Australian Resident

5 = Foreign Resident

8 = Working holiday makers

4 = Sub-Contractor

1

YesYesYes
tax_freeTax Free Threshold Claimed

Boolean

1YesYesYes

help

HELP PAYG tax

Boolean

0

YesYesYes
tslTrade Support Loan

Boolean

0YesYesYes
sfssStudent Financial Supplement Scheme

Boolean

0YesYesYes
senior_taxSeniors and Pensioners Tax Offset

Boolean

0YesYesYes

tax_per

Fixed Tax percentage

Integer - Percentage

20

YesYesYes

tax_add

Tax offset

-1000 to +1000 - Dollar value

50

YesYesYes

etfn

Tax File Number

Numeric

321 321 321

YesNo
No, due to the sensitive nature of TFNs they can not be exported

The export will include either "not_set" or "set" instead.

super_fundSuper 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

YesYesYes refer to super_fund array

super_no

super_no_2

super_no_3

super_no_4

Super Member NumberAplanumeric655655655YesYesYes

super_fund_2

super_fund_3

super_fund_4

= Additional employer super

= Salary Sacrifice

= After tax contribution
Yes refer to super_fund arrayYes refer to super_fund arrayNoNoYes refer to super_fund array

basichours

Basic hours

Decimal - Hours

38

YesNoYes

salary

Salary

T=True

F=False

T

YesNoYes

status

Employment status

Full Time,F,f,FT,FULLTIME

Casual,C,c,CA,CASUAL

Part Time,P,p,PT,PARTTIME

Sub-Contractor

Full Time

YesNoYes as bold option
active
Active or Terminated


TRUE=TRUE

FALSE=TRUE

TRUENo, employee will be active when first addedYesYes

entitledal

Entitled annual leave weeks

Decimal - Weeks

4

YesNoYes

rdo

Rostered day off hours deducted

Integer - Hours

2

YesNoYes

leaveloading

Annual leave loading

Decimal - Percentage

17.5

YesNoYes

entitledsickleave

Entitled personal leave

Decimal - Weeks

2

YesNoYes

entitled_long

Entitled long service leave

Decimal - 1 week in x

60

YesNoYes

preacal

Pre-accumulated annual leave

Decimal - Hours

123.32

YesNoYes

pre_long

Pre-accumulated long service leave

Decimal - Hours

123.32

YesNoYes

pre_sick

Pre-accumulated personal leave

Decimal - Hours

123.32

YesNoYes

prerdo

Pre-accumulated RDO

Decimal - Hours

123.32

YesNoYes

prenet

Pre-accumulated net

Decimal - Dollar

10000.22

YesNoYes

presuper

Pre-accumulated super above 9.5

Decimal - Dollar

10000.22

YesNoYes

pretax

Pre-accumulated tax

Decimal - Dollar

10000.22

YesNoYes

pregross

Pre-accumulated gross

Decimal - Dollar

10000.22

YesNoYes

eTitle

Bank title account 1

String

Mr John Smith

YesYesYes

eBSB

Bank BSB account 1

xxx-xxx

111-222

YesYesYes

eAccountNo

Bank account no account 1

Numeric

123123123

YesYesYes

split_pay

Split pay to account 2

nul,{blank}=NA

fix=Fix amount

per=Percentage

fix

YesNoYes

split_amount

Split amount to account 2

Decimal - Percentage or Amount

200

YesNoYes

eTitle2

Bank title account 2

String

Mr John Smith

YesNoYes

eBSB2

Bank BSB account 2

xxx-xxx

111-222

YesNoYes

eAccountNo2

Bank account number account 2

Numeric

111222333

YesNoYes

split_pay3

Split pay to account 3

nul,{blank}=NA

fix=Fix amount

per=Percentage

nul

YesNoYes

split_amount3

Split amount to account 3

Decimal - Percentage or Amount

0

YesNoYes

eTitle3

Bank title account 3

String


YesNoYes

eBSB3

Bank BSB account 3

xxx-xxx


YesNoYes

eAccountNo3

Bank account number account 3

Numeric


YesNoYes
EmployeeIDYour systems employee IDAlphanumeric

55555

Used not recordedNANA

duplicate_check

Checks if a user already exists via emailString=emailemailYesNANA

auto_username

Forces a username to be created in the format firstname_lastnameX

X is incremented until a unique username is found

1
0
1YesNANA

welcome

Sends out welcome message via email and/or SMS auto_username must be truesms
email
both
smsYesNANA





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 nameValue - 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 or eusername must be included so Microkeeper knows which fields to update
  • Not all fields can be updated, only commonly changed fields are recorded
  • All 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


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.

Recommend implementation would run at a set interval, for example every 7 days where the last_modified field was set 7 days ago.


Step 1

Set the mk_action variable and mk_data variable.

Variable nameValues and Example
mk_action

get_employees

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




Step 2

Review data standards


Refer to table above for exported formats


super_fund array


Variable nameDescriptionOutput formatExample

SFID

Super Fund IDInteger111

name

The common name of the fundStringAMP Personal Super Plan

ABN

Australia Business Number of Super Fund

This is not always recorded unless a SMSF is selected
Number76514770399

USI


Unique Super Identifier
Recommended to identify a fund
Not recorded for SMSF

Alphanumeric76514770399003

spin

Superannuation Product Identification Number

This should not be used as two different funds can share the same number
AlphanumericAMP0278AU


groups array


Variable nameDescriptionOutput formatExample

GID

Group ID as recorded in Microkeeper
If record present employee is in this group
Integer111

per


Percentage for cost centre tracking
Between 0 - 100

Decimal100




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","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

Array

(

    [success] => 1

    [authenticated] => 1

    [message] => 2 staff retrieved from Microkeeper

    [data] => Array

        (

             [employees] => Array

                (

                    [0] => Array

                         (

                             [EID] => 3

                             [eusername] => john_smith

                             [firstname] => John

                             [lastname] => Smith

                             [email] => john@test.com

                             [phoneno] => 0401655555

                             [home_no] =>

                             [kin_name] => John Smith

                             [kin_no] => 0438555555

                             [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

                             [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] => Array

                                 (

                                     [SFID] => 482

                                     [name] => REST Employer  Sponsored Division

                                     [ABN] =>

                                     [USI] => RES0103AU

                                     [spin] => RES0103AU

                                 )

                             [super_no] => 111111

                             [super_fund_2] => Array

                                 (

                                     [SFID] => 712

                                     [name] => Amp endowment personal  super plan

                                     [ABN] => 76514770399

                                     [USI] => 76514770399003

                                     [spin] =>

                                 )

                            [super_no_2] => 111112

                            [super_fund_3] => Array

                                 (

                                     [SFID] => 46

                                     [name] => AMP SuperLeader  Plan

                                     [ABN] =>

                                     [USI] => AMP0278AU

                                     [spin] => AMP0278AU

                                )

                             [super_no_3] => 111113

                             [super_fund_4] => Array

                                 (

                                     [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 John Smith2

                             [eBSB2] => 222-222

                             [eAccountNo2] => 2222

                             [split_pay3] => fix

                             [split_amount3] => 33.00

                             [eTitle3] => Mr John Smith3

                             [eBSB3] => 066-333

                             [eAccountNo3] => 33333

                             [default_job] => 909

                             [position] => CEO

                             [groups] => Array

                                 (

                                    [0] => Array

                                         (

                                             [GID] => 1703

                                             [per] => 100

                                         )

                                     [1] => Array

                                        (

                                             [GID] => 1630

                                             [per] => 100

                                         )

                                     [2] => Array

                                         (

                                             [GID] => 1425

                                             [per] => 100

                                         )

                                    [3] => Array

                                         (

                                             [GID] => 1295

                                             [per] => 100

                                         )

                                     [4] => Array

                                         (

                                             [GID] => 1702

                                             [per] => 100

                                        )

                                     [5] => Array

                                         (

                                             [GID] => 1296

                                             [per] => 100

                                         )

                                 )

                         )

                )

        )

)