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 or APPROVED 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
email	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

🚧Additional Security Required

Additional Authentication

Retrieving HR Onboarding Data

Sample Response

Data Elements

🚧
Additional Security Required