Retrieving an Employee's HR/Payroll data [New!]
Additional Security Required
To use the HR Onboarding API you must be an approved software vendor. There are additional security requirements that must be met by your company before you can gain access to this API. For more information visit https://deputy.typeform.com/to/BJV7ZTEl
There must be a valid use case for your software to be able to gain access to this API and filling out an application does not necessarily mean acceptance.
The Deputy HR Onboarding API allows you to access additional secured employee information for integration with your software. Items such as tax details, bank account numbers and other information that can make payroll onboarding easier is available in this API.
Additional Authentication
Along with the regular bearer tokens used for the Deputy API, an additional security header is required to be included in all payloads to the endpoint. This token is included in the following header:
X-DP-HR-ONB-TOKEN
- This token is a locally generated JWT (JSON Web Token). Deputy will provide you with a private key enabling you to generate the tokens, once your access to the API is approved.
Retrieving HR Onboarding Data
Once you have all the security requirements met, to connect to the HR Onboarding API use the following URL.
curl --GET 'https://{install}.{geo}.deputy.com/api/hr/v2/employees/{employeeid}/onboarding/export'
This will retrieve the employees onboarding information. However there are a few scenarios to note:
- If the employee was not onboarded using the Deputy HR onboarding system you will receive a 400 response
- Only employees which have a
SUBMITTED
orAPPROVED
status will be returned in the HR Onboarding API. In draft state employees are still able to make changes and so it does not make sense to sync the data at that point.
Sample Response
{
"success": true,
"data": {
"superfundAU": {
"fund": {
"ABN": "70732426024",
"USI": "70732426024100",
"productName": "MLC MasterKey Business Super (including MLC MasterKey Personal Super)"
},
"declareTrueAndCorrect": true,
"option": "Yes",
"type": "employeeNominated",
"selfManaged": "",
"taxFileNumber": {
"number": "123456782"
},
"fundMember": "1458745",
"name": "sdsgfdsgfsdgf"
},
"personalDetails": {
"emergencyContactMobile": {
"number": "420463805",
"countryCode": "+61"
},
"emergencyContactRelationship": "Brother",
"preferredName": "",
"address": {
"sublocality": "City of Sydney",
"addressLines": [
"1 Smail Street"
],
"organization": "",
"recipients": null,
"locality": "Ultimo",
"administrativeArea": "NSW",
"regionCode": "AU",
"revision": 0,
"sortingCode": "",
"postalCode": "2007",
"languageCode": "EN_AU"
},
"email": "[email protected]",
"gender": "PREFER_NOT_TO_SAY",
"emergencyContactName": "sdfdsfsdf",
"dob": "2023-01-02"
},
"taxDetailsAU": {
"taxDetails": {
"helpLoan": "no",
"sfssLoan": "no",
"declareTrueAndCorrect": true,
"payBasis": "full-time",
"taxFreeThreshold": "no",
"residentStatus": "resident"
},
"number": "123456782",
"personalDetails": {
"title": "Mr",
"fullName": "sdfsfsf"
},
"option": "Yes",
"reason": ""
},
"bankDetailsAU": {
"accountName": "dsfsdfsdf",
"bsbNumber": "062217",
"accountNumber": "234245234"
}
}
}
Data Elements
Element | Data Type | Info |
---|---|---|
success | Boolean true/false | Defines whether the API request was successful or not. Will be either true or false. |
data | Object | Contains the object response for the employee onboarding data |
superfundAU | Object | Contains information relevant to superannuation in Australia |
superfundAU - fund | Object | Contains specific information about the super fund the employee has chosen during onboarding |
superfundAU - fund - ABN | String | Contains the ABN (Australian Business Number) of the super fund chosen by the employee |
superfundAU - fund - USI | String | Contains the USI (Related to superstream) of the super fund chosen by the employee during onboarding |
superfundAU - find productName | String | Contains a plain text name of the Super fund chosen by the employee during onboarding |
declareTrueAndCorrect | Boolean true/false | Whether the employee has declared all the information they have provided is true and correct. Will be either true or false. |
type | String | The type of super fund enrollment. Whether the employer enrolled the employee into the superfund (as it might be their first job for example) or whether the employee nominated an existing superfund account during onboarding. |
selfManaged | Unused | Reserved for future development |
taxFileNumber | Object | Contains information about the tax details provided for the employee related to the super fund. |
taxFileNumber - number | String | The tax file number provided |
fundMember | String | The superannuation member number provided by the employee when onboarding |
personalDetails | Object | Contains information such as emergency contact for the employee |
personalDetails - emergencyContactMobile | Object | Contains mobile phone information related to the emergency contact for the employee |
personalDetails - emergency ContactMobile - number | String | The mobile number (without country code) for the emergency contact |
personalDetails - emergencyContactMobile - countryCode | String | The country code for the mobile eg +61 for Australia |
emergencyContactRelationship | String | How the emergency contact is related to the employee |
preferredName | String | Preferred name of the employee |
address | Object | Contains information about the employees address |
address - subLocality | String | The local government area of the employee |
address - addressLines | Array | Contains the lines for the street address of the employee |
address - organization | String | |
address - recipients | ||
address - locality | String | The suburb of the employees address |
address - administrativeArea | String | The state of the employees address |
address - regionCode | String | The region code for the employees address for example AU - Australia, UK - United Kingdom etc. |
address - revision | ||
address - sortingCode | String | |
address - postalCode | String | The post code for the employees address |
address - languageCode | String | |
String | The email address for the employee | |
gender | String | Which gender the employee has identified as during the onboarding process. Employee can also choose prefer not to say. |
emergencyContactName | String | The name of the emergency contact |
dob | String | The date of birth of the employee in YYYY-MM-DD format. |
taxDetailsAU | Object | If the employee is an Australian employee this object will be included. It is related to the tax file declaration the employee has made |
taxDetailsAU - helpLoan | String | Whether the employee has indicated they have a HELP loan student debt or not. Can be yes or no. |
taxDetailsAU - sfssLoan | String | Whether the employee has indicated they have a SFSS loan debt or not. Can be yes or no. |
declareTrueAndCorrect | Boolean true/false | Whether the employee has declared the tax file declaration information as true and correct. Can be true or false. |
payBasis | String | The pay basis of the employee. Can be full-time, part-time, casual. |
taxDetailsAU - taxFreeThreshold | String | Whether the employee is claiming the tax free threshold on this job. Can be yes or no. |
taxDetailsAU - residentStatus | String | The residency status of the employee at the time of onboarding. |
number | String | The phone number for the employee |
personalDetails | Object | Contains information about the employee including name |
personalDetails - title | String | The title of the employee for example mr, ms etc. |
personalDetails - fullName | String | The full name of the employee |
option | ||
reason | ||
bankDetailsAU | Object | Contains information about the employees bank account. |
bankDetailsAU - accountName | String | The name of the bank account |
bankDetailsAU - bsbNumber | String | The BSB number of the bank account |
bankDetailsAU - accountNumber | String | The account number of the bank account |
Updated 2 months ago