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"
  }
}

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.

ElementDataTypeInfo
firstNameStringThe first name of the employee
lastNameStringThe last name of the employee
displayNameStringThe preferred display name for the employee
otherNameStringThe other name (perhaps middle name) of the employee
salutationStringThe salutation of the employee
positionStringThe position/job title of the employee
primaryLocationObjectThe primary location of the employee
primaryLocation - NameStringString matching field for the employees primary location
primaryLocation - idIntegerUses the location id instead of string matching to define the employees primary location
ContactObjectObject that contains
Contact - email1StringThe primary email address for the employee
Contact - phone1StringThe primary phone for the employee
Contact - email2StringThe secondary email address for the employee
Contact - phone2StringThe secondary phone number for the employee
Contact - notesStringAny notes to add against the employee profile
Contact - webStringAny website associated with the employee
Contact - faxStringThe fax number of the employee
mainAddressObjectObject that contains data which has information about the primary address of the employee
mainAddress - contactNameStringThe contact name for the address
mainAddress - unitNoStringThe unit number for the address
mainAddress - streetnoStringThe street number for the address
mainAddress - suiteNoStringThe suite number for the address
mainAddress - poBoxStringThe PO Box number for the address
mainAddress - streetStringThe street name for the address
mainAddress - street2StringAny additional street name for the address
mainAddress - suburbStringThe suburb for the address
mainAddress - countryStringThis is a string however it is the number which represents the country in the Deputy app. This is found using the countries endpoint.
mainAddress - stateStringThis is a string however it is the number which represents the state in the Deputy app. This is found using the state endpoint.
mainAddress - postcodeStringThe postcode for the address
mainAddress - phoneStringThe phone number for the address
mainAddress - notesStringAny notes for the address
mainAddress - formatInteger
emergencyAddressObjectThe details for the emergency address of the employee
emergencyAddress - contactNameStringThe contact name for the emergency address
emergencyAddress - formatInteger
emergencyAddress - phoneStringThe phone number for the emergency address
postalAddressObjectThe details for the postal address of the employee
postalAddress - unitNoStringThe unit number for the postal address of the employee
postalAddress - contactNameStringThe contact name for the postal address of the employee
postalAddress - streetNoStringThe street number for the postal address of the employee
postalAddress - suiteNoStringThe suite number for the postal address of the employee
postalAddress - poBoxStringThe po box number for the postal address of the employee
postalAddress - streetStringThe street for the postal address of the employee
postalAddress - street2StringThe second street for the postal address of the employee
postalAddress - suburbStringThe suburb for the postal address of the employee
postalAddress - countryStringThis is a string but is the number which represents the company in the Deputy database
postalAddress - StateStringThis is a strong but is the number which represents the state in the Deputy database
postalAddress - postcodeStringThe postcode for the postal address of the employee
postalAddress - phoneStringThe phone for the postal address of the employee
postalAddress - notesStringThe notes for the postal address of the employee
postalAddress - formatInteger
genderobjectThis object contains gender information for the emplyoee
gender - genderIdStringString matching field for the gender field in the employees profile
pronounsobjectThis object contains pronoun information for the employee
pronouns - pronounsIdStringString matching field for the pronouns field in the employees profile
customPronounsStringA field to add a custom pronoun against an employees profile
higherDutyBoolean true/false
roleobjectThis object contains which Deputy role this employee should be set to
role - nameStringString matching element which defines what Deputy role the employee has
dateOfBirthStringThe date of birth for the employee. Format YYYY-MM-DD
startDateStringThe zulu time of the employess start date
terminationDateStringThe zulu time of the employees termination date
WorkplacesArrayThis array contains additional locations which have been assigned to the employee
Workplaces - locationObjectThis object contains information about a location being added to the employees profile
Workplaces - location - locationStringString 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 - idIntegerThis allows you to use the workplace id instead of the string if your app knows this number.
Workplaces - agreementObjectContains information about the workplace agreement for the employee for that location.
Workplaces - agreement - payrollIdStringThe payroll id to be used with the workplace agreement
Workplaces - agreement - payPeriodIntegerEnterprise only. Represents the pay period for the employee.
Workplaces - agreement - payCenter - IdIntegerEnterprise only. The id of the pay center the employee is linked to.
Workplaces - contractObjectContains information about the employment contract for the employee.
Workplaces - agreement - contract - nameStringThe 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 - startDateString Date/Time ZuluThe start date of the of employment agreement
Workplaces - agreement - endDateString Date/Time ZuluThe end date of the employment agreement
trainingRecords - moduleIdInteger
trainingRecords - isActiveBoolean true/falseWhether the training record is active on the employees profile
trainingRecords - trainingDateStringString which contains the date the training was completed. Format YYYY-MM-DD
trainingRecords - expiryDateStringString which contains the date the training expires. Format YYYY-MM-DD
trainingRecords - commentStringString which contains a comment for the training record
stressProfileObjectObject that contains information about the stress profile
stressProfile - idIntegerThe id of the stressProfile to be added to the employees profile.
userObjectContains information required to have the user added to the Deputy system
user - loginStringCan be a simple string on an email address. This is what the employee will use for the login field in Deputy.
user - sendInviteBoolean true/falseAllows 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.
externalIdGUIDThe 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.