^ Login

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

Integer12345NoNo (1)Yes
eusername
Employee username

Unique identifier

Standardised
"firstname_lastnameX"

Read auto_username
John_smith
No, but can be automatically generated

No (1)Yes
EmployeeIDEmployee ID in 3rd party system

Unique identifier

Alphanumeric

Must be set to "blank" or Unique

emp_001YesNo (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

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

YesNo - Used as a security checkpointYes

startdate2

Start date

dd/mm/yyyy or yyyy-mm-dd

2014-10-20

YesYesYes

terdate2

Termination date

dd/mm/yyyy or yyyy-mm-dd

2014-10-20

YesYesYes
cessation_typeCessation TypeSingle Char - OptionsDYesYesYes

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

I,Indeterminate

O,Other

M

YesYesYes as bold option

rate

Pay rate

Decimal - Dollar value

16.1943

YesYesYes
RRNIDRate Rule Name IDInteger1234YesYesYes

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
abnSub-Contractor ABN
Only used if status is set to Sub-Contractor
Integer82004832237YesYesYes

businessname


Sub-Contractor Business Name
Only used if status is set to Sub-Contractor
StringABC Contractor Pty LtdYesYesYes
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_A

Bank BSB account 1

xxx-xxx

or

xxxxxx

or

xxxxx

011-222

or

011222

or

11222

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

eBSB_B

Bank BSB account 2

xxx-xxx

or

xxxxxx

or

xxxxx

011-222

or

011222

or

11222

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

eBSB_C

Bank BSB account 3

xxx-xxx

or

xxxxxx

or

xxxxx

011-222

or

011222

or

11222

YesNoYes

eAccountNo3

Bank account number account 3

Numeric


YesNoYes
default_LIDDefault Location
Integer

7656YesYesYes
default_ROIDDefault Role
Integer

2343YesYesYes
default_job
Default Job

Can be found by mousing over ID in Job list

Integer1234YesNoYes
primary_managerUsername of primary managerstringjohn_smithYesNoYes
position
Position of employee

stringCFOYesNoYes

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
smsYesNA

NA

custom_{ID}

Custom fields created and managed by the employer.
example custom_favourite_pizza
StringHawaiian Pizza
YesYesYes



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



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 or can be set to "active".

If you intend of 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.


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"}
or
{"config":{"last_modified":"active"}




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 fund.StringAMP 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" ,"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"
          }
        ]
      }
    ]
  }
}