Update Employee Data

This section focuses on:

• Structure of PUT requests to users for basic profile updates
• Structure of POST requests to the assignment endpoints for assignment updates
• Important constraints for email and mobile_number

Update employee profile in 7shifts

Use the PUT /api/v2/company/{id}/users/{user_id} endpoint to update employee profile fields.

This request should be used for updates like:

• first_name
• last_name
• mobile_number
• email
• other supported profile fields (address, language, notes, etc.)

You only need to include fields that changed.

📘

Account model (important context) Users are company-level records. When a person works at multiple companies, 7shifts links those user records to one shared login account.

For integrations, treat this as:

• Login username = email
• Changing a user email changes the username the person uses to log in

Email and phone constraints

Before syncing email or phone fields, follow these rules:

1. Email is not always freely editable
   1. If a user is part of a shared cross-company account, email updates may be rejected.
   2. If accepted, changing email changes the user’s login username.
2. Phone is also protected in shared-account scenarios
   1. mobile_number updates may be rejected when the user is part of a shared cross-company account.
   2. Equivalent formatting changes (for example, country code normalization) may still be accepted.
3. Email cannot always be cleared
   1. Setting email to empty may be rejected for users that already have a login account.
4. Email must be unique within the company
   1. Reusing an email already used by another active or inactive user in the same company is rejected.
5. Email update attempts are rate-limited
   1. Repeated email changes in a short period can be blocked temporarily.

Recommended sync workflow for email/phone

Before sending PUT with email or phone fields:

1. GET /api/v2/company/{id}/users/{user_id}
2. Compare your source value vs current 7shifts value
3. Only send fields that actually changed
4. Handle 400 validation responses as non-retryable business-rule failures (unless your data changes)

Request URL

curl --request PUT --url 'https://api.7shifts.com/v2/company/12335/users/1111'

Request body

{
     "first_name": "Bertram",
     "last_name": "Gilfoyle",
     "mobile_number": "3065558888"
}

Please note the following about the above request:

• The request URL must specify the id of the 7shifts user to be updated.
• You only need to specify the fields that got updated, although it wouldn’t make a difference if you specified all the fields in the request body.

Error handling (business-rule 4XX only)

Use this table for validation/conditional failures that come from request data and user state.

Updating LDR and Wage Assignments

We provide endpoints to modify locations, departments and role assignment for each user. Before you proceed you must have a clear understanding of 7shifts mapping specified in our Mapping guide. Additionally your implementation must have a synchronized table for each location, department and role ID's and how they map to your system.

Referencing the previous POST, here we provide an example PUT request to the assign the existing user to yet another role with the ID 55555 which exists under department ID 33333 at location 22222, which is another location under the same company, for a $15.00 wage:

Request URLs

curl --request POST \
	--url 'https://api.7shifts.com/api/v2/company/1234/users/1111/location_assignments' \
  --data '{"location_id":22222}'

curl --request POST \
	--url 'https://api.7shifts.com/api/v2/company/1234/users/1111/department_assignments' \
  --data '{"department_id":33333}'

curl --request POST \
	--url 'https://api.7shifts.com/api/v2/company/1234/users/1111/role_assignments' \
  --data '{"role_id":555555}'

TIP The POST /role_assignments includes logic to add a location and department if they are not assigned to the user. For the example above you only needed to make the last call to assign the location, department and role for user 1111

When removing assignments, use the DELETE action for the endpoints. NOTE deleting assignments will cascade the changes down to their children objects. If you delete a user location assignment, it will also delete the associated department and role assignments.

Example request to remove a department assignment 8256 from a user 1111:

curl --request DELETE --url https://api.7shifts.com/api/v2/company/1234/users/1111/department_assignments/8256

Changing Wage Type

Did an employee just switch from being on an hourly wage to a weekly salary? When updating the user wage you must set a new wage with the wage_type = weekly_salary with a new effective date and wage_cents value.

The same can be done when switching from weekly salary to hourly wage.

curl --request POST \
     --url 'https://api.7shifts.com/v2/company/1234/users/1111/wages' \
     --data '
{
     "role_id": 555555,
     "effective_date": "2022-06-01",
     "wage_type": "hourly",
     "wage_cents": 1500
}'

Unassigning locations, departments and roles

You can use the following endpoints to remove assignments. Each endpoint will cascade the changes down so if a location is removed from a users assignments, it will remove the related departments and roles.

• DELETE Location Assignment
• DELETE Department Assignment
• DELETE Role Assignment