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.

curl --GET 'https://{install}.{geo}.deputy.com/api/management/v2/employees?fieldMask=firstName&cursor=RW1wbG95ZWU6NTA

In the example above, the cursor element is being used to retrieve further data.

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.

Element	DataType	Info
firstName	String	The first name of the employee
lastName	String	The last name of the employee
displayName	String	The preferred display name for the employee
otherName	String	The other name (perhaps middle name) of the employee
salutation	String	The salutation of the employee
position	String	The position/job title of the employee
primaryLocation	Object	The primary location of the employee
primaryLocation - Name	String	String matching field for the employees primary location
primaryLocation - id	Integer	Uses the location id instead of string matching to define the employees primary location
Contact	Object	Object that contains
Contact - email1	String	The primary email address for the employee
Contact - phone1	String	The primary phone for the employee
Contact - email2	String	The secondary email address for the employee
Contact - phone2	String	The secondary phone number for the employee
Contact - notes	String	Any notes to add against the employee profile
Contact - web	String	Any website associated with the employee
Contact - fax	String	The fax number of the employee
mainAddress	Object	Object that contains data which has information about the primary address of the employee
mainAddress - contactName	String	The contact name for the address
mainAddress - unitNo	String	The unit number for the address
mainAddress - streetno	String	The street number for the address
mainAddress - suiteNo	String	The suite number for the address
mainAddress - poBox	String	The PO Box number for the address
mainAddress - street	String	The street name for the address
mainAddress - street2	String	Any additional street name for the address
mainAddress - suburb	String	The suburb for the address
mainAddress - country	String	This is a string however it is the number which represents the country in the Deputy app. This is found using the countries endpoint.
mainAddress - state	String	This is a string however it is the number which represents the state in the Deputy app. This is found using the state endpoint.
mainAddress - postcode	String	The postcode for the address
mainAddress - phone	String	The phone number for the address
mainAddress - notes	String	Any notes for the address
mainAddress - format	Integer
emergencyAddress	Object	The details for the emergency address of the employee
emergencyAddress - contactName	String	The contact name for the emergency address
emergencyAddress - format	Integer
emergencyAddress - phone	String	The phone number for the emergency address
postalAddress	Object	The details for the postal address of the employee
postalAddress - unitNo	String	The unit number for the postal address of the employee
postalAddress - contactName	String	The contact name for the postal address of the employee
postalAddress - streetNo	String	The street number for the postal address of the employee
postalAddress - suiteNo	String	The suite number for the postal address of the employee
postalAddress - poBox	String	The po box number for the postal address of the employee
postalAddress - street	String	The street for the postal address of the employee
postalAddress - street2	String	The second street for the postal address of the employee
postalAddress - suburb	String	The suburb for the postal address of the employee
postalAddress - country	String	This is a string but is the number which represents the company in the Deputy database
postalAddress - State	String	This is a strong but is the number which represents the state in the Deputy database
postalAddress - postcode	String	The postcode for the postal address of the employee
postalAddress - phone	String	The phone for the postal address of the employee
postalAddress - notes	String	The notes for the postal address of the employee
postalAddress - format	Integer
gender	object	This object contains gender information for the emplyoee
gender - genderId	String	String matching field for the gender field in the employees profile
pronouns	object	This object contains pronoun information for the employee
pronouns - pronounsId	String	String matching field for the pronouns field in the employees profile
customPronouns	String	A field to add a custom pronoun against an employees profile
higherDuty	Boolean true/false
role	object	This object contains which Deputy role this employee should be set to
role - name	String	String matching element which defines what Deputy role the employee has
dateOfBirth	String	The date of birth for the employee. Format YYYY-MM-DD
startDate	String	The zulu time of the employess start date
terminationDate	String	The zulu time of the employees termination date
Workplaces	Array	This array contains additional locations which have been assigned to the employee
Workplaces - location	Object	This object contains information about a location being added to the employees profile
Workplaces - location - location	String	String matching element which defines the locations name. This element can also be id which allows you to put the integer which defines the id of the location.
Workplaces - location - id	Integer	This allows you to use the workplace id instead of the string if your app knows this number.
Workplaces - agreement	Object	Contains information about the workplace agreement for the employee for that location.
Workplaces - agreement - payrollId	String	The payroll id to be used with the workplace agreement
Workplaces - agreement - payPeriod	Integer	Enterprise only. Represents the pay period for the employee.
Workplaces - agreement - payCenter - Id	Integer	Enterprise only. The id of the pay center the employee is linked to.
Workplaces - contract	Object	Contains information about the employment contract for the employee.
Workplaces - agreement - contract - name	String	The name of the contract. This is used to match to the name of an existing contract in the Deputy install to apply to the employee agreement.
Workplaces - agreement - startDate	String Date/Time Zulu	The start date of the of employment agreement
Workplaces - agreement - endDate	String Date/Time Zulu	The end date of the employment agreement
trainingRecords - moduleId	Integer
trainingRecords - isActive	Boolean true/false	Whether the training record is active on the employees profile
trainingRecords - trainingDate	String	String which contains the date the training was completed. Format YYYY-MM-DD
trainingRecords - expiryDate	String	String which contains the date the training expires. Format YYYY-MM-DD
trainingRecords - comment	String	String which contains a comment for the training record
stressProfile	Object	Object that contains information about the stress profile
stressProfile - id	Integer	The id of the stressProfile to be added to the employees profile.
user	Object	Contains information required to have the user added to the Deputy system
user - login	String	Can be a simple string on an email address. This is what the employee will use for the login field in Deputy.
user - sendInvite	Boolean true/false	Allows you to determine whether an invite to Deputy should be sent to the employee when added. If this is set to true, as soon as the employee is added to Deputy, an email will be sent to them inviting them to setup an account for the mobile app etc. Use cautiously.
externalId	GUID	This is an echo field and is not saved in Deputy. You can use this field to set a GUID on that record, which will be returned in the externalId field on the response back. Note: It does not save the externalId if you want a record id to save that you can use with the API in future requests, you should use externalLinkId.
externalLinkId	GUID	The unique identifying GUID for the employee from an external system. This can be very useful for third party developers where you need a field to store for example the GUID id record number from your own application.

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-e28818009867and 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 theexternalLinkIdelement 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.