Updating an employee using the Employee V2 API gives you more flexibility than ever before. Rather than having to include the entire payload to update an employee, you can now include only that which you want to update in the payload. As well as this you can define what fields you would like in the response, allowing you as the developer to define just how little or how much data you want to be returned from Deputy once the update has completed.

URL and Payload

URL

curl --location --request PATCH 'https://{install}.{geo}.deputy.com/api/management/v2/employees/{id}'

In this sample we will be updating the address of an employee with the id of 422

So the URL is

https://{install}.{geo}.deputy.com/api/management/v2/employees/422

The sample code is below

{
    "data": {
        "firstName": "Rachel",
        "lastName": "Green",
        "primaryLocation": {
            "id": "1"
        },
        "mainAddress": {
            "unitNo": "456",
            "streetNo": "23",
            "street": "Beach Street",
            "suburb": "Manly"
        }
    }
}

For this scenario, Rachel Green has informed HR that recently the family moved to a new address. This needs to be updated electronically in Deputy by a third party application the company Rachel works for handles HR with. As you can see, this payload will update Rachel's address to be 456/23 Beach Street Manly.

For updating an employee the firstName, lastName and primaryLocation id number must all be included in the payload. From that point you can choose to only include what pieces of information is being updated, so even though the employee API has significant amounts of objects available, not all of them are mandatory when updating an employee.

You will then receive this response once sending the payload

{
    "success": true,
    "result": {
        "data": {
            "id": "422",
            "primaryLocation": {
                "id": "1"
            },
            "firstName": "Rachel",
            "lastName": "Green",
            "displayName": "Rachel Green",
            "otherName": "Rach",
            "salutation": "Ms",
            "pronouns": {
                "pronounsId": "SHE_HER",
                "pronouns": "She/Her"
            },
            "customPronouns": "Custom/Pronouns",
            "mainAddress": {
                "id": "359",
                "contactName": "maine",
                "unitNo": "456",
                "streetNo": "23",
                "suiteNo": "Suite",
                "poBox": "23456",
                "street": "Street",
                "street2": "Sesame",
                "suburb": "Manly",
                "state": {
                    "id": "21",
                    "name": "Georgia"
                },
                "postcode": "2000",
                "country": "Australia",
                "phone": "45466",
                "notes": "note here",
                "format": "0"
            },
            "postalAddress": {
                "id": "352",
                "contactName": "Postal",
                "unitNo": "123",
                "streetNo": "2345",
                "suiteNo": "Suite",
                "poBox": "23456",
                "street": "Streeet",
                "street2": "Sesame",
                "suburb": "Sydney",
                "state": {
                    "id": "13",
                    "name": "Arkansas"
                },
                "postcode": "2000",
                "country": "Australia",
                "phone": "45466",
                "notes": "note here",
                "format": "1"
            },
            "contact": {
                "id": "2186",
                "phone1": "123345",
                "phone2": "1233045",
                "fax": "23245435",
                "phone1Type": "Mobile",
                "phone2Type": "Personal",
                "email1": "[email protected]",
                "email1Type": "Work",
                "email2Type": "Personal",
                "email2": "[email protected]",
                "web": "sdfsdf",
                "notes": "notes here"
            },
            "emergencyAddress": {
                "id": "351",
                "contactName": "Sandra Jones",
                "phone": "45466"
            },
            "dateOfBirth": "2001-04-01",
            "gender": {
                "genderId": "FEMALE",
                "gender": "Female"
            },
            "user": {
                "login": "rgreen",
                "sendInvite": false
            },
            "active": true,
            "startDate": "2024-02-11T13:00:00Z",
            "stressProfile": {
                "id": "1",
                "name": "24/7",
                "maxHoursPerShift": 24,
                "maxHoursPerPeriod": 168,
                "maxDaysPerPeriod": 7,
                "maxHoursPerDay": 24,
                "gapHoursBetweenShifts": 0,
                "createdAt": "2009-06-11T07:20:47Z",
                "modifiedAt": "2012-10-04T09:12:18Z"
            },
            "trainingRecords": [],
            "higherDuty": true,
            "role": {
                "id": "50"
            },
            "allowAppraisal": true,
            "history": "6007",
            "workplaces": [
                {
                    "id": "424",
                    "location": {
                        "id": "1"
                    },
                    "sortOrder": 0,
                    "agreement": {
                        "id": "423",
                        "payCenter": {
                            "id": "1"
                        },
                        "active": true,
                        "startDate": "2024-02-11T13:00:00Z",
                        "payrollId": "883456999",
                        "payPeriod": "1",
                        "history": "1118",
                        "createdAt": "2024-02-11T23:00:00Z",
                        "modifiedAt": "2024-02-11T23:00:01Z"
                    },
                    "createdAt": "2024-02-11T23:00:00Z",
                    "modifiedAt": "2024-02-11T23:00:00Z"
                },
                {
                    "id": "425",
                    "location": {
                        "id": "2"
                    },
                    "sortOrder": 1,
                    "agreement": {
                        "id": "424",
                        "payCenter": {
                            "id": "2"
                        },
                        "active": true,
                        "startDate": "2024-02-11T13:00:00Z",
                        "payPeriod": "1",
                        "history": "1119",
                        "createdAt": "2024-02-11T23:00:00Z",
                        "modifiedAt": "2024-02-11T23:00:01Z"
                    },
                    "createdAt": "2024-02-11T23:00:00Z",
                    "modifiedAt": "2024-02-11T23:00:00Z"
                }
            ],
            "createdAt": "2024-02-11T23:00:00Z",
            "modifiedAt": "2024-02-11T23:47:39Z"
        }
    }
}

As you can see a significant amount of data is returned. It is possible to specific to receive only data relevant to your application by using field masks. Here is the same example, using field masks to only retrieve what is relevant to the calling application.

{
    "data": {
        "firstName": "Rachel",
        "lastName": "Green",
        "primaryLocation": {
            "id": "1"
        },
        "mainAddress": {
            "unitNo": "456",
            "streetNo": "23",
            "street": "Beach Street",
            "suburb": "Manly"
        }
    }
},
"fieldMask": "id, firstName,lastName"
}

When this payload is sent only the requested fields will be returned which can make it much easier to parse the data coming back from the Deputy system.

{
    "success": true,
    "result": {
        "data": {
            "id": "422",
            "firstName": "Rachel",
            "lastName": "Green",
            "trainingRecords": [],
            "workplaces": []
        }
    }