Adding an employee in Deputy is a quite common use case for the API. You can easily sync new employees from own system into Deputy, ready to have shifts and timesheets associated with them. For the addition of new employees to Deputy, we recommend that you use the management endpoints, known as supervise. The process is detailed below

URL and Payload

URL

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

Sample

{
	"data": {
		"firstName": "Michael",
		"lastName": "Jones",
		"displayName": "Michael Jones",
		"otherName": "James",
		"salutation": "Mr.",
		"position": "Employee",
		"primaryLocation": {
			"id": "1"
		},
		"contact": {
			"email1": "[email protected]",
			"phone1": "123345",
			"phone2": "1233045",
			"email2": "[email protected]",
			"notes": "notes here",
			"web": "https://www.deputy.com",
			"fax": "23245435"
		},
		"mainAddress": {
			"contactName": "maine",
			"unitNo": "123",
			"streetNo": "2345",
			"suiteNo": "Suite",
			"poBox": "23456",
			"street": "Street ",
			"street2": "Sesame",
			"suburb": "Sydney",
			"country": "13",
			"state": {
				"id": "21"
			},
			"postcode": "2000",
			"phone": "45466",
			"notes": "note here",
			"format": 1
		},
		"emergencyAddress": {
			"contactName": "Sandra Jones",
			"format": 1,
			"phone": "45466"
		},
		"postalAddress": {
			"unitNo": "123",
			"contactName": "Postal",
			"streetNo": "2345",
			"suiteNo": "Suite",
			"poBox": "23456",
			"street": "Streeet ",
			"street2": "Sesame",
			"suburb": "Sydney",
			"country": "13",
			"state": {
                "id": "13"
            },
			"postcode": "2000",
			"phone": "45466",
			"notes": "note here",
			"format": 1
		},
		"gender": {
			"genderId": "MALE"
		},
		"pronouns": {
			"pronounsId": "HE_HIM"
		},
		"customPronouns": "Custom/Pronouns",
		"higherDuty": true,
		"dateOfBirth": "2001-04-01",
		"startDate": "2019-05-21T14:00:00Z",
		"workplaces": [{
				"location": {
					"id": "1"
				},
				"agreement": {
					"payrollId": "883456999",
					"contract": {
						"id": "1"
					}
				}
			},
			{
				"location": {
					"id": "2"
				}
			}
		],
		"stressProfile": {
			"id": 1
		},
		"externalId": "70abb134-0601-4297-9e8f-73f2960357b3"
	}
}

Response

{
    "success": true,
    "result": {
        "data": {
            "id": "581",
            "primaryLocation": {
                "id": "1"
            },
            "firstName": "Michael",
            "lastName": "Jones",
            "displayName": "Michael Jones",
            "otherName": "James",
            "salutation": "Mr.",
            "pronouns": {
                "pronounsId": "NOT_SPECIFIED",
                "pronouns": "Not specified"
            },
            "contact": {
                "id": "106574",
                "phone1": "123345",
                "phone2": "1233045",
                "fax": "23245435",
                "phone1Type": "Mobile",
                "phone2Type": "Personal",
                "email1": "[email protected]",
                "email1Type": "Work",
                "email2Type": "Personal",
                "email2": "[email protected]",
                "web": "https://www.deputy.com",
                "notes": "notes here"
            },
            "user": {
                "login": "m2jones",
                "sendInvite": false
            },
            "active": true,
            "startDate": "2023-04-27T14: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": false,
            "role": {
                "id": "50"
            },
            "allowAppraisal": true,
            "history": "115659",
            "workplaces": [
                {
                    "id": "673",
                    "location": {
                        "id": "1"
                    },
                    "sortOrder": 0,
                    "agreement": {
                        "id": "672",
                        "payCenter": {
                            "id": "1"
                        },
                        "active": true,
                        "startDate": "2023-04-27T14:00:00Z",
                        "payPeriod": "1",
                        "history": "3960",
                        "createdAt": "2023-04-28T03:26:01Z",
                        "modifiedAt": "2023-04-28T03:26:01Z"
                    },
                    "createdAt": "2023-04-28T03:26:01Z",
                    "modifiedAt": "2023-04-28T03:26:01Z"
                }
            ],
            "createdAt": "2023-04-28T03:26:01Z",
            "modifiedAt": "2023-04-28T03:26:01Z"
        }
    }
}

Data Elements

Data Element	Mandatory	Info
strFirstName	Yes	First name of the employee
strLastName	Yes	Last name of the employee
displayName	Yes	How the employees name should be displayed in Deputy
position	No	The employees position in the company, also known as the role in Deputy. This can be the following: - Employee - Supervisor - Location Manager - System Administrator Note: For Enterprise this can be the name of any role within the Deputy install.
primaryLocation	No	Object which contains information about the primary location for the employee
primaryLocation - id	No	An integer which represents the id of the primary location for the employee
contact - object	No	This object contains information about the contact details for the employee.
contact - email1	No	The primary email for the employee
contact - phone1	No	The primary phone number for the employee
contact - phone2	No	The secondary phone number for the employee
contact - notes	No	Notes for the employees profile
contact - web	No	The website for the employee
contact - fax	No	The fax number for the employee
mainAddress - object	No	This object has information related to the employees primary address
mainAddress - contactName	No	The main contact name related to the employees main address
mainAddress - unitNo	No	The unit number for the address
mainAddress - streetNo	No	The street number for the address
mainAddress - suiteNo	No	The suite number for the address
mainAddress - poBox	No	The po box number for the address
mainAddress - street	No	The first street details for the address
mainAddress - street2	No	The second street details for the address
mainAddress - suburb	No	The suburb details for the address
mainAddress - country	No	The id in Deputy which represents the country the address is for
mainAddress - state	No	The id in Deputy which represents the state the address is for
mainAddress - postcode	No	The postcode for the address
mainAddress - phone	No	The phone for the address
mainAddress - notes	No	Any notes related to the address
mainAddress - format	No	Always 1
emergencyAddress Object	No	This object contains information about the address for the emergency details contact for the employee
emergencyAddress - contactName	No	The contact name for the emergency address
format	No	Always 1
emergencyAddress - phone	No	The phone number for the emergency address
postalAddress - object	No	This object contains details about the postal address for the employee
postalAddress - unitNo	No	The unit number related to the postal address
postalAddress - contactName	No	The contact name related to the postal address
postalAddress - streetNo	No	The street number related to the postal address
postalAddress - suiteNo	No	The suite number related to the postal address
postalAddress - poBox	No	The post office box related to the postal address
postalAddress - street	No	The first street related to the postal address
postalAddress - street2	No	The second street related to the postal address
postalAddress - suburb	No	The suburb related to the postal address
postalAddress - country	No	The id in the Deputy database related to the country of the postal address
postalAddress - state	No	The id in the Deputy database related to the state of the postal address
postalAddress - postcode	No	The postcode related to the postal address
postalAddress - phone	No	The phone number related to the postal address
postalAddress - notes	No	The notes related to the postal address
postalAddress - format	No	Always 1
gender - object	No	This object contains information related to the employees gender
genderId - gender	No	The id of the gender related to the employee.
pronouns - object	No	This object contains information related to the employees pronouns
pronouns - pronounsId	No	Contains the employees pronouns. Can be He/Him, She/Her, Them/They
customPronouns	No	If the employee has custom pronouns set this will be added here
higherDuty	No	Boolean. Whether the employee has a higher duty or not.
dateOfBirth	No	The employees data of birth in YYYY-MM-DD format
startDate	No	The employees start date in YYYY-MM-DD format
workplaces - Array	No	Contains an array of all the workplaces (locations) the employee is related to in the Deputy install
workplaces - location object	No	This object contains information about a location in the Deputy install related to the employee. There can be multiple of these within the workplaces array if the employee has more than one location set in the Deputy install.
workplaces - location - id	No	The id of the location within the Deputy install related to this workplace object
workplaces - agreement object	No	This object contains information about the agreement related to that workplace (location) for the employee within the Deputy install
workplaces - agreement - payrollid	No	The payroll id related to this agreement for the employee
workplaces - agreement - contract - contractId	No	This is the id of the employment contract related to this employee when working in this workplace (location) in the Deputy install
trainingRecords - array	No	Contains information about training records related to the employee in the Deputy install
trainingRecords - module
trainingRecords - isActive	No	Boolean true/false. Whether the training record is currently considered valid within the employees record. For example has not expired
trainingRecords - trainingDate	No	When the training was completed. YYYY-MM-DD format.
trainingRecords - expiryDate	No	When the current training record is due to expire. YYYY-MM-DD format.
trainingRecords - comment	No	The current comments against the training record
stressProfile - object	No	Contains information about the stress profile currently assigned to the employee
stressProfile - id	No	The id of the stress profile currently linked to the employee in the Deputy install.
externalId	No	This field allows you to set a string which you can use to relate back to your own system for easy data matching. For example you might include the unique GUID record from your own system for this employee in this field, to assist in future data matching.

Employee API V1

Documentation relating to the old employee API Version 1 can be found here Employee API V1