These docs are for v2.2022.0501. Click to read the latest docs for v2.2023.0501.

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 & role mapping must be completed in order for the integration to know which location, department & 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

curl --request POST --url 'https://api.7shifts.com/v2/company/1234/users'

Request body

{
     
     "first_name": "John",
     "last_name": "Doe",
     "email": "[email protected]",
     "mobile_number": 3061234454,
     "type": "employee",
     "language": "en",
     "location_ids": [
          12345
     ],
     "department_ids": [
          98765
     ]
}

Here’s an explanation of each of the fields required in the request body:

ParameterTypeDescription
first_namestringThe first name of the employee. Can’t be blank.
last_namestringThe last name of the employee. Can’t be blank. First name & last name combo must be unique.
emailstringThe email address of the employee, this should not be changed once set as it’s used for logging into 7shifts. Must be unique.
mobile_phoneintegerThe mobile phone number of the employee, this is where they’ll receive SMS notifications and an invite to join 7shifts.
typestringThe employee type. Always set to employee
languagestringLanguage type. Always set to en
location_idsarrayArray of location_ids of the 7shifts locations(s) assigned to the user.
department_idsarrayArray of location_ids of the 7shift departments assigned to the user. Department IDs are required if the assigned location has at least one department.

A successful user creation request will result in a "status": "success" response with all the details of the created user. Please store the id field from the response, as that’s the unique identifier that you’ll need to use for updating the user in the future.

To assign the roles for the user you will need to call the POST Role Assignment endpoint.

Here is a sample request to add the role 1029 to user 1111:

curl --request POST --url 'https://api.7shifts.com/api/v2/company/1234/users/1111/role_assignments'

With the request body specifying the role:

{
  "role_id": 1029
}

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 user that the first name/last name combo and/or email 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

For every role or department that needs to be assigned the hierarchy above it must make sense as well. If you try to assign a role to a user that does not belong to any of the specified 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, departments & 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 & 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.

Tips

You should have a field in your database that is used to track the 7shifts 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.

To simplify the assignment process for users the POST Role Assignment endpoint will automatically add the location and department assignments to the user without having to call the POST Location Assignment and POST Department Assignment if they aren't assigned to the user.

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 you are able to set the 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 assignment wage data to an employees roles:

Request URL

curl --request POST --url 'https://api.7shifts.com/v2/company/12345/users/1111/wages'

Request body

{
     "role_id": 1029,
     "wage_type": "hourly",
     "wage_cents": 2300,
     "effective_date": "2022-06-01"
}

Here’s a quick description of what each of the fields in the wages object array represents:

ParameterTypeDescription
role_idintegerID of the role that this wage is associated to. Set to null if roles are not supported
wage_centsintegerIn cents, the amount representing the wage.
effective_dateDateThe date on which this wage goes into effect
wage_typestringSet to weekly_salary for salaried users and hourly for hourly wage users.

A couple of things to note here:

  • If an employee is assigned a weekly salary instead of an hourly wage, set wage_type to weekly_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 the date that the user is created.

Role-Agnostic Wage

Does your system not support different wages for each role, i.e., do you only support one wage per user? If so, you can just specify one role-agnostic wage object in the body, and set the 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

Does your system support per-role wages, i.e., a separate wage for each role? 7shifts does support this, and you can check whether the user has enabled this in their 7shifts account by making the following request and checking if the wage_based_roles is set to true:

NOTE: use the V1 /companies endpoint. The wage_based_roles parameter will be included in the response payload for /companies in V2 soon.

curl --request GET  --url '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 to be created is on hourly wages, you must specify a wage each role specified for the user.