Retrieving an Employee

Overview

The main improvement from the new employee API is a drastic reduction in the the amount of API requests needed to have an employee ready to use in Deputy (that is, being able to be assigned shifts, paid, enter timesheets etc). Currently on average with the existing API it takes 12 requests for an employee to be added, but now you can complete these tasks in a single request in most cases.

Once you have been granted access, you can access the new employee API via the following URL.

URL

curl --POST 'https://{install}.{geo}.deputy.com/api/management/v2/employees

You can include as much or as little as you need for your app

One of the major changes to the employee API is that we have implemented a structure where you can send significant payloads and cover all the bases if required, but if not the API also accepts smaller payloads just fine.
The minimum data to create an employee is firstName, lastName and their primaryLocation.

📘

Pagination

Pagination is supported in the V2 Employee API. This is handled by the nextCursor element. If a nextCursor element exists in the response and has an entry, it means there is more data to retrieve. You can retrieve the next page of the data by including the generated cursor in the query parameters for the next request.

Field Masks

The new API also introduces field masks for the first time. This allows you to define exactly what data you would like back from the API instead of having to receive data not relevant to your use case. By requesting only the data types that you need, you can also increase security of your application by only storing what is relevant.

Using field masks with the employee API is quite simple. A new element called fieldMask is added to the end of the payload just after the data object. In there you can define what fields you would like to include in the response from the Deputy system. Take for example the below code sample

{
  "data": {
    "firstName": "Mike",
    "lastName": "Person",
    "primaryLocation": {
      "id": "1"
    }
  },
  "fieldMask": "firstName,lastName"
}

As you can see at the end of the payload we are defining an element called fieldMask and including firstName and lastName. What this means is that even though we are defining a primaryLocation in our payload, we are only wanting the firstName and lastName (along with the record id) in the response. This allows you to specifically target what data is important to your application. Your field mask also does not need to match the payload your application is sending. This means you can send a significant amount of data, but only record the information back from the system that your app may require.

You can also achieve this with a GET request by adding a fieldMask parameter to the URL. For example

curl --GET 'https://{install}.{geo}.deputy.com/api/management/v2/employees?fieldMask=firstName,lastName,displayName

In the example above, the API will only return the first name, last name and display name for the employee. This again allows you to specifically target what data is relevant for your use case and nothing your application does not need.

Sample Employee Payload

{
  "data": {
    "firstName": "testb",
    "lastName": "testb",
    "displayName": "Testy Too",
    "otherName": "other name",
    "salutation": "Mr.",
    "position": "Employee",
    "primaryLocation": {
      "id": "1"
    },
    "contact": {
      "email1": "[email protected]",
      "phone1": "123345",
      "phone2": "1233045",
      "email2": "[email protected]",
      "notes": "notes here",
      "web": "sdfsdf",
      "fax": "23245435"
    },
    "mainAddress": {
      "contactName": "maine",
      "unitNo": "123",
      "streetNo": "2345",
      "suiteNo": "Suite",
      "poBox": "23456",
      "street": "Street ",
      "street2": "Sesame",
      "suburb": "Sydney",
      "country": "13",
      "state": {
        "name": "Tasmania"
      },
      "postcode": "2000",
      "phone": "45466",
      "notes": "note here",
      "format": 1
    },
    "emergencyAddress": {
      "contactName": "Emergency",
      "phone": "45466"
    },
    "postalAddress": {
      "unitNo": "123",
      "contactName": "Postal",
      "streetNo": "2345",
      "suiteNo": "Suite",
      "poBox": "23456",
      "street": "Streeet ",
      "street2": "Sesame",
      "suburb": "Sydney",
      "country": "13",
      "state": {
        "name": "Tasmania"
      },
      "postcode": "2000",
      "phone": "45466",
      "notes": "note here",
      "format": 1
    },
    "gender": {
      "genderId": "PREFER_NOT_TO_SAY"
    },
    "pronouns": {
      "pronounsId": "HE_HIM"
    },
    "customPronouns": "Custom/Pronouns",
    "higherDuty": true,
    "dateOfBirth": "2001-04-01",
    "startDate": "2019-05-21T14:00:00Z",
    "terminationDate": "2022-05-21T14:00:00Z",
    "workplaces": [
      {
        "location": {
          "id": "1"
        },
        "agreement": {
          "payrollId": "883456999",
          "contract": {
            "id": "1"
          }
        }
      },
      {
        "location": {
          "id": "2"
        },
        "agreement": {
          "payrollId": "123456000",
          "payPeriod": "1",
          "payCenter": {
            "id": "2"
          },
          "contract": {
            "name": "A sample contract"
          },
          "startDate": "2019-05-21T14:00:00Z",
          "endDate": "2022-05-21T14:00:00Z"
        }
      }
    ],
    "trainingRecords": [
      {
        "module": 1,
        "isActive": true,
        "trainingDate": "2023-01-01",
        "expiryDate": "2024-06-30",
        "comment": "Emotional Intelligence Training"
      }
    ],
    "stressProfile": {
      "id": 1
    },
    "user": {
      "login": "testb",
      "sendInvite": true
    },
    "externalId": "70abb134-0601-4297-9e8f-73f2960357b3",
    "externalLinkId": "96d20e59-5533-4746-b3b1-e28818009867"
  }
}

As you can see from the sample, a number of items which previously required additional requests such as training records and stress profiles, can be set in the original request.

📘

Bulk Importing

The API also supports adding multiple employees at the same time. Simply put the employee data inside an array and add :bulk to the end of the endpoint URL.

📘

String Matching

Some of the fields in the new API support string matching. However it should be noted that this is not fuzzy matching and must match exactly (aside from case) including spaces. Some such examples are locations, contracts and stress profiles

Primary Contact Details

This part of the API is mandatory when adding an employee to the Deputy system, it is the only object which is mandatory in the entire payload.

Updating an employee record

To update an employee record you can use the PATCH method. The URL for this is as follows.

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

The id represents the unique id of the employee. It is also possible to bulk patch employees. To do this, include the employee object data in an array of records, and add :bulk to the end of the url.

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

Again like the addition of employees, you can update as little or as much as you want. Existing data in employee records will not be removed if it is not included in the payload, so for example if only a last name is changing, there is no need to include the whole record anymore.

Note: If you are updating Embedded Deputy users, you will also need to pass their partnerUserId. See more here.

Patch masking

Like when adding or getting employee data, when updating data you can tell the system what fields are specifically being updated. Take for example the following payload.

{
  "data": {
    "id": "4",
    "firstName": "Sue",
    "lastName": "Jones",
    "primaryLocation": {
      "id": "1"
    },
    "stressProfile": {
      "id": "3"
    }
  },
  "fieldMask": "id,firstName,stressProfile",
  "patchMask": "firstName,stressProfile.id"
}

In this payload we are telling the API we are only want the id, firstName and stressProfile information to be returned in response, but we are also defining that only the firstname and stressProfile.id has been changed. Other information is included as its the minimum, but you can include information about specifically changed records. This allows you to use the same structure as an 'add' employee request from your app as a data object, but tell the Deputy system what fields have specifically changed.

Defining an External Link ID for an employee record

One of the most challenge pieces that software developers will deal with when building integrations to any product is how best to connect the systems via their individual records. Generally this is done by a GUID or other unique metric, but occasionally is done by payroll ID or the like which can cause issues, especially if that record entry is editable.

To assist with this we have added an externalLinkId field to the Employee v2 API. This allows you to set a string which will be saved in the database and references that employee. For example you might have a CRM application that has the GUID 96d20e59-5533-4746-b3b1-e28818009867 and you want to save or link that record to an employee in Deputy.

One of the easiest ways to ensure this ongoing link is to use the externalLinkId element in the Employee v2 API to save the linking GUID. Once you have done this, you are able to retrieve that employee with the following GET request.

curl --GET 'https://{install}.{geo}.deputy.com/api/management/v2/employees?externalLinkId[]={externalLinkId}

This will then retrieve the specific record which matches that externalLinkId. In a scenario where no matching employee is found, an empty array will be returned.