Create Employee Data
This section focuses on:
- Structure of POST requests to the /users endpoint:
- Get familiar with the request you need to create a user with role info in 7shifts
- Create employee profile in 7shifts
- Create employees with wage data
Post structure for /users
Employee data in 7shifts can be created through the /users endpoint, one user at a time. Location, department, and role mapping must be completed in order for the integration to know which location, department, and role in 7shifts the user needs to be assigned to.
An example POST request to the /users endpoint to create an employee with the relevant information would look as follows. In this example, we’re creating an employee that’s assigned to two different roles:
Request URL
POST https://api.7shifts.com/v1/users
Request body
{
"user": {
"firstname": "Bertram",
"lastname": "Gilfoyle",
"email": "[email protected]",
"mobile_phone": 3065558888,
"active": true,
"user_type_id": 1
},
"role": [
{
"id": 135790
},
{
"id": 864280
}
],
"department": [
{
"id": 98765
}
],
"location": [
{
"id": 12345
}
]
}
Here’s an explanation of each of the fields required in the request body:
Parameter | Type | Description |
---|---|---|
user.first_name | Text | The first name of the employee (cannot be left blank) |
user.last_name | Text | The last name of the employee (cannot be left blank). First name & last name combo must be unique. |
user.email | Text | The email address of the employee - this should not be changed once set as it’s used for logging into 7shifts. Must be unique. |
user.mobile_phone | Integer | The mobile phone number of the employee - this is where they’ll receive SMS notifications and an invite to join 7shifts. |
user.active | Boolean | Whether the user should be active in 7shifts or not - should always be true when creating new employees. |
user.user_type_id | Integer | Must always be set to 1, denoting that the user profile being created is of the type ‘Employee’. |
role.id | Integer | The ID(s) of the 7shifts role(s) that the user needs to be assigned to. |
location.id | Integer | The ID(s) of the 7shifts department(s) that each of the role.ids belong to, and any department(s) that the user needs to be assigned to without a role. |
department.id | Integer | The ID(s) of the 7shifts location(s) that each of the role.ids and department.ids belong to. |
"status": "success"
response with all the details of the created user. Please store the user.id field from the response, as that’s the unique identifier that you’ll need to use for updating the user in the future.Errors to look out for
Same name/email error
The first name + last name combo must be unique in every 7shifts company. Similarly, the email address field must be unique per company as well.
If you receive the following response, you will need to warn the user that the first name/last name combo and/or email belong to must be updated in your system before it can be synced to 7shifts:
{
"status": "error",
"message": "User with name John Smith or email [email protected] already exists",
"type": "validation_error"
}
Incorrect assignment hierarchy error
department.ids
, or if you try to assign a department to a user that does not belong to any of the specified location.ids
, you will encounter an error as follows:{
"status": "error",
"message": "User is assigned to a department without being assigned to that department's location.",
"type": "validation_error"
}
Creating employee profiles
Upon first enabling the integration, you should check whether all locations, department, and roles have been mapped. If they have been mapped, then you should check if any employees that exist in both systems have been mapped.
Any existing active employee profiles in your system that haven’t already been mapped to an employee in 7shifts should be created in 7shifts using the POST request structure from the previous sub-section for each active employee.
Again, please ensure that only Employee profiles are being sent over, as Admin, Manager, and Assistant Manager profiles must be created in 7shifts to avoid unexpected permission issues.
Once that initial sync is done, the integration must be built so that as soon as an employee profile is created in your system, a corresponding employee profile gets created in 7shifts as well.
Tip
You should have a field in your database that is used to track the 7shifts user ID (user.id) of the created or mapped user. This will help understand whether there’s already a corresponding user in 7shifts for the user in question in your system.
This will also help with the next sections, where if a user has already been created/mapped into 7shifts, then the integration must update the existing 7shifts user instead of creating a new one.
Creating employees with wage data
If the scope of your integration includes syncing wage data into 7shifts, the POST request described earlier can be extended to include wage data as well, so that the created employee will have wage data in 7shifts.
This is what an example POST request will look like for creating an employee with two assigned roles and the respective wage data:
Request URL
POST https://api.7shifts.com/v1/users
Request body
{
"user": {
"firstname": "Bertram",
"lastname": "Gilfoyle",
"email": "[email protected]",
"mobile_phone": 3065558888,
"active": true,
"user_type_id": 1
},
"role": [
{
"id": 135790
},
{
"id": 864280
}
],
"department": [
{
"id": 98765
}
],
"location": [
{
"id": 12345
}
],
"wages": [
{
"role_id": 135790,
"wage_cents": 2300,
"effective_date": "2020-12-01",
"wage_type": "hourly",
"is_deleted": false
},
{
"role_id": 864280,
"wage_cents": 1700,
"effective_date": "2020-12-01",
"wage_type": "hourly",
"is_deleted": false
}
]
}
wages
object array represents:Parameter | Type | Description |
---|---|---|
role_id | Integer | ID of the role that this wage is associated to. |
wage_cents | Integer | In cents, the amount representing the wage. |
effective_date | Date | The date on which this wage goes into effect |
wage_type | String | Set to weekly_salary for salaried users and hourly for hourly wage users. |
is_deleted | Fixed/Boolean | Mandatory field that needs to be supplied in the body, always leave it set to false. |
Wage Assignment Logic Tree
The logic tree for wage assignment is as follows:
- If the user has a weekly salary: Specify just one wage object with
wage_type = weekly_salary
&role_id = null
- If the user has an hourly wage: Make a GET request to v1/companies & check if
wage_based_roles = true
- If
wage_based_roles = true
: Specify each necessary wage object withwage_type = hourly
& set the respectiverole_id
- If
wage_based_roles = false
: Specify just one wage object withwage_type = hourly
&role_id = null
- If
A couple of things to note here:
- If an employee is assigned a weekly salary instead of an hourly wage, set
wage_type
toweekly_salary
. In this case,wage_cents
must specify the total amount in cents that the user will be making in one week. - If your system doesn’t support effective future wage dates, you can always simply specify
effective_date
to be “today”/the date that the user is being created.
Role-Agnostic Wage
role_id
to null
.Try to avoid this role-agnostic wages implementation to not limit certain functionality in 7shifts. If possible, please opt for the following ‘Per-Role Wage’ implementation.
Per-Role wage
wage_based_roles
is set to true
:GET https://api.7shifts.com/v1/companies
If wage_based_roles
is returned as false
, you can ask the administrator user to turn it on in 7shifts first. A 7shifts administrator can find this setting under Company Settings > Labor & Compliance > Wages & Pay > Wage-based Roles.
If wage_based_roles
is returned as true
and as long as the user about to be created is on hourly wages, you must specify a wage object in the body for each respective role specified in the role object array. Even if a wage doesn’t exist for one of the roles in your system, you must specify the object in the array, and set wage_cents
to 0
for that role’s respective wage object in the request body.
Updated 1 day ago