Updating an Employee
Inevitably if your application adds employees to Deputy, it will at some point need to update an employee record. It might be a change of address, a phone number or even their name that needs updating but this is easily achieved using the Deputy API.
URL
curl --location --request POST 'https://{install}.{geo}.deputy.com/api/v1/supervise/employee/{id}'
Due to the fact this is targeted towards a single employee, the employees record id must be included in the URL. If your application has not stored this id or you are updating an existing employee for the first time and do not know the id, it can be retrieved using the Get details for all employees endpoint.
What can be updated
The Deputy API offers applications the ability to update the vast majority of employee details. There is one notable exception to this. If an employee has accepted an invitation to sign up for Deputy then you will not be able to update their mobile phone or email address. The employee will have to make this change themselves in the Deputy app. If you try to update these records and an invite has been accepted, you will receive this response:
{
"error": {
"code": 400,
"message": "Cannot change contact details to employee who has accepted invitation"
}
}
Inactive Employees
Inactive employees are unable to be edited by the Deputy API. To make any change to these records your application will first need to change the active status of the employee. However you will need to make it clear to your users when making a change to active status, this will have an effect on their real-time employee count within Deputy which could affect their billing amount.
Sample Request to update employee
In this sample we are going to update the mobile phone.
{
"strMobilePhone": "044987654"
}
Even if you do not include all the other data within the payload, it will not be removed. For example, not including the first and last name of the employee does not remove that data from the record. In the response, the whole employee record is included
Sample response of updating an employee
{
"Id": 101,
"Company": 1,
"FirstName": "John",
"LastName": "Doe",
"DisplayName": "Joey Smith",
"OtherName": null,
"Salutation": null,
"MainAddress": null,
"PostalAddress": null,
"Contact": 102512,
"EmergencyAddress": null,
"DateOfBirth": null,
"Gender": null,
"Pronouns": 0,
"CustomPronouns": null,
"Photo": null,
"UserId": 101,
"JobAppId": null,
"Active": true,
"StartDate": "2022-05-26T00:00:00+10:00",
"TerminationDate": null,
"StressProfile": 1,
"Position": null,
"HigherDuty": null,
"Role": 50,
"AllowAppraisal": true,
"HistoryId": 107406,
"CustomFieldData": null,
"Creator": 1,
"Created": "2022-05-26T17:09:22+10:00",
"Modified": "2022-09-05T11:48:32+10:00",
"_DPMetaData": {
"System": "Employee",
"CreatorInfo": {}
},
"IsSubordinate": true,
"WorkplaceArray": [
{
"Id": 104,
"EmployeeId": 101,
"Company": 1,
"SortOrder": 0,
"Agreement1": 103,
"Agreement2": null,
"Agreement3": null,
"Creator": 1,
"Created": "2022-05-26T17:09:22+10:00",
"Modified": "2022-05-26T17:09:22+10:00",
"_DPMetaData": {
"System": "EmployeeWorkplace",
"CreatorInfo": {}
}
}
],
"TrainingArray": "",
"TrainingFileArray": [],
"LeaveAccrualArray": [],
"PayrollId": "",
"Contract": "",
"SalaryDistributionConfig": null,
"Email": null,
"Mobile": "044987654",
"PhotoLinkId": "",
"Img": "https://d11hmzhsuwuq9f.cloudfront.net/my/avatar?name=J+S&width=30&height=30",
"Status": 3,
"CanAskToShowPin": true,
"HasIPhoneToken": false,
"HasAndroidToken": false,
"HasEnabled2FA": false,
"AnalyticsID": "d41d8cd98f00b204e9800998ecf8427e",
"UserName": "jsmith",
"AllowLogin": true,
"OnboardingStatus": 1001
}
Updating an employees pay rate
If your application is payroll related, you may have a need to update the pay rates for employees (for example their base hourly pay). How this is achieved depends on whether you are applying a library rate or not.
Basic pay rates
Basic pay rates (such as the basic weekday hourly rate) are currently unable to be updated via the Deputy API. If you would like to request this as a feature please contact [email protected]
Library rates
Deputy Awards and Agreements
While Deputy takes care to provide a quality pay rules library, it does not guarantee (or accept responsibility for) the accuracy, completeness or up-to-date nature of the library, or that it will be suitable for the particular circumstances of your business. You're advised to consult with your legal and payroll advisers before relying on Deputy's interpretation.
When you want to apply or update an employees pay rate for their library award, the first task is to get the pay rate id using the Resource API endpoint with the EmploymentContract object.
If the employee already has an agreement, the name of the award/agreement the employee currently has applied will be included in the Name element of the Contract object in the response from the Get details for a employee by id endpoint.
You can then use this name as a filter on the Resource API endpoint.
URL
curl --location --request POST 'https://{install}.{geo}.deputy.com/api/v1/resource/employmentcontract/QUERY'
To ensure we only obtain the details for the specific award/agreement we are looking for, the search option from the resource api will be used.
Sample Request to retrieve an employment contract
{"search":{
"s1":{ "field": "Name", "data": "TP [MA000049] AEA - Junior - Casual - 1-November-2021", "type": "eq"}
}}
In this example, we are searching for the agreement with the name TP [MA000049] AEA - Junior - Casual - 1-November-2021. If we search the employment contract query endpoint without including a search, a bulk response of agreements will be returned.
[
{
"Id": 224,
"Code": "au/casual-2021-11-01-aea-junior-2",
"Name": "TP [MA000049] AEA - Junior - Casual - 1-November-2021",
"Description": "e71ee9b0bda85ace366c290b8054f2de",
"EmploymentBasis": 1,
"EmploymentCategory": 1,
"EmploymentStatus": 3,
"EmploymentCondition": 2,
"BasePayRule": 20350,
"StressProfile": null,
"StartDate": null,
"EndDate": null,
"PeriodType": 1,
"File": null,
"StrictLeaveApproval": null,
"Award": "AEA",
"EmploymentSubType": "junior",
"AwardStartDate": "2021-11-01T00:00:00+11:00",
"Creator": 1,
"Created": "2022-09-07T12:25:55+10:00",
"Modified": "2022-09-07T12:25:55+10:00",
"_DPMetaData": {
"System": "EmploymentContract",
"CreatorInfo": {
"Id": 1,
"DisplayName": "Simon Hutchinson",
"EmployeeProfile": 1,
"Employee": 1,
"Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_1e4417bce8404f8facdfe89990f3bedb.jpg?Expires=1662682677&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=GxK56fhfUJZNQQqGabB9m49UiuRodQqQLa963UVKPGjiCWu52sRvXQ3O2MWFTSxJIwzN0AvASzmpggQmoYBLZdfG9IqSwLeFnA-uDp4VnNcPlNDQiLynbFSB0YFNleba4I~xQVzYBqoSw~DI6paz6TGbxEQalWbM0cjFYvcUAmA_",
"Pronouns": 0,
"CustomPronouns": ""
}
}
}
We can then use this information to update an employees payrate. The key information you need from the above response is the award code au/casual-2021-11-01-aea-junior-2 and the BasePayRule. This is important because it is these two pieces of data that link together for an employees pay contract and pay rate.
Once we have this information we can proceed to update the employees pay rate.
URL
To set an award or update an award from the Deputy library rates you use the Set award for employee endpoint.
curl --location --request POST 'https://{install}.{geo}.deputy.com/api/v1/supervise/employee/{employeeid}/setAwardFromLibrary'
Sample Request to update an employees pay rate
{
"strCountryCode": "au",
"strAwardCode": "casual-2021-02-12-ratesperday-1",
"arrOverridePayRules": [
{
"Id": 20350,
"HourlyRate": 90
}
]
}
Here we are including the country of the award, the award code, and then setting the new rate for the employee. The Id is the pay rule against this employee. This allows you to update this employee's base pay rate without affecting other employees that have that award attached to their profile as well.
Base Pay Rate
Only the base pay rate can be updated/added via this endpoint as the awards system in Deputy then uses that to calculate all the penalties and overtime rates applicable to that award.
Once this is completed you will get this response
{
"Id": 1,
"Company": 1,
"FirstName": "John",
"LastName": "Doe",
"DisplayName": "John Doe",
"OtherName": null,
"Salutation": null,
"MainAddress": 195,
"PostalAddress": 195,
"Contact": 101184,
"EmergencyAddress": null,
"DateOfBirth": null,
"Gender": 0,
"Pronouns": 0,
"CustomPronouns": "",
"Photo": 931,
"UserId": 1,
"JobAppId": null,
"Active": true,
"StartDate": "2022-05-05T00:00:00+10:00",
"TerminationDate": null,
"StressProfile": 1,
"Position": null,
"HigherDuty": null,
"Role": 1,
"AllowAppraisal": true,
"HistoryId": 105907,
"CustomFieldData": null,
"Creator": 1,
"Created": "2022-05-05T16:42:21+10:00",
"Modified": "2022-07-29T11:55:56+10:00",
"_DPMetaData": {
"System": "Employee",
"CreatorInfo": {}
},
"IsSubordinate": true,
"WorkplaceArray": [
{
"Id": 123,
"EmployeeId": 1,
"Company": 8,
"SortOrder": 5,
"Agreement1": 122,
"Agreement2": null,
"Agreement3": null,
"Creator": 1,
"Created": "2022-08-10T11:31:25+10:00",
"Modified": "2022-08-10T11:31:25+10:00",
"_DPMetaData": {
"System": "EmployeeWorkplace",
"CreatorInfo": {}
}
}
],
"TrainingArray": "",
"TrainingFileArray": [],
"LeaveAccrualArray": [],
"PayrollId": "",
"Contract": {
"Id": 246,
"Code": "au/casual-2021-02-12-ratesperday-1",
"Name": "TP Rates per Day",
"Description": "a16f9fea577c124590c4ac5b209e6fd0",
"EmploymentBasis": 1,
"EmploymentCategory": 1,
"EmploymentStatus": 3,
"EmploymentCondition": 4,
"BasePayRule": 507,
"StressProfile": null,
"StartDate": null,
"EndDate": null,
"PeriodType": 1,
"File": null,
"StrictLeaveApproval": false,
"Award": "Rates per Day",
"EmploymentSubType": null,
"AwardStartDate": "2021-02-12T00:00:00+11:00",
"Creator": 1,
"Created": "2022-09-13T15:23:52+10:00",
"Modified": "2022-09-13T15:23:52+10:00",
"_DPMetaData": {
"System": "EmploymentContract",
"CreatorInfo": {}
},
"ThirdPartySync": "",
"PayRuleArray": [
{
"Id": 507,
"PayTitle": "Mondays",
"RemunerationType": 1,
"RemunerationBy": 1,
"AnnualSalary": null,
"HourlyRate": 90,
"IsMultiplier": false,
"MultiplierValue": null,
"MultiplierBaseRate": null,
"MinimumType": 3,
"MaximumType": 3,
"MinimumValue": null,
"MaximumValue": null,
"MinimumShiftLength": null,
"MaximumShiftLength": null,
"AdvancedCalculation": null,
"IsExported": true,
"UnitValue": null,
"Schedule": 332,
"RecommendWith": 1,
"DexmlScript": null,
"DexmlScriptParam": null,
"PeriodType": null,
"PayPortionRule": 2,
"PayrollCategory": "MONDAY",
"Comment": "",
"RateType": null,
"RateTag": null,
"Creator": 1,
"Created": "2022-09-13T15:23:52+10:00",
"Modified": "2022-09-13T15:23:52+10:00",
"_DPMetaData": {
"System": "PayRules",
"CreatorInfo": {}
}
}
],
"LeaveRuleArray": [
{
"Id": 322,
"ContractId": 246,
"LeaveRuleId": 11,
"BasePayRule": -2,
"LoadingPayRule1": null,
"LoadingPayRule2": null,
"LoadingPayRule3": null,
"Creator": 1,
"Created": "2022-09-13T15:23:52+10:00",
"Modified": "2022-09-13T15:23:52+10:00",
"_DPMetaData": {
"System": "EmploymentContractLeaveRules",
"CreatorInfo": {}
}
},
{
"Id": 323,
"ContractId": 246,
"LeaveRuleId": 12,
"BasePayRule": -2,
"LoadingPayRule1": null,
"LoadingPayRule2": null,
"LoadingPayRule3": null,
"Creator": 1,
"Created": "2022-09-13T15:23:52+10:00",
"Modified": "2022-09-13T15:23:52+10:00",
"_DPMetaData": {
"System": "EmploymentContractLeaveRules",
"CreatorInfo": {}
}
},
{
"Id": 324,
"ContractId": 246,
"LeaveRuleId": 13,
"BasePayRule": null,
"LoadingPayRule1": null,
"LoadingPayRule2": null,
"LoadingPayRule3": null,
"Creator": 1,
"Created": "2022-09-13T15:23:52+10:00",
"Modified": "2022-09-13T15:23:52+10:00",
"_DPMetaData": {
"System": "EmploymentContractLeaveRules",
"CreatorInfo": {}
}
}
],
"MigrateTo": null
},
"SalaryDistributionConfig": null,
"Email": null,
"Mobile": ""
}
The employee's profile is then updated. The response will contain information about the employee, their payroll contracts and leave details. Below the Contract object data elements are explained in detail.
Updated over 1 year ago