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

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:

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

{
    "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.

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

A couple of things to note here:

Role-Agnostic Wage

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

GET https://api.7shifts.com/v1/companies