Move Employee

This guide walks you through moving an employee to a different unit in Quinyx. You will learn how to update the employee's home unit and transition their role assignments to the new group.

Note: Changing an employee's home unit does not automatically update their role assignments. You must terminate the old assignments and create new ones manually, as described in steps 4 and 5.

1. 1

   Read the employee's current state

   Fetch the employee before you change anything. This gives you the homeGroupId you are moving them off, which you need to recognize the matching role assignments in step 3, and a baseline to compare against once the move is done.

   curl 'https://api.eu.quinyx.com/hr/v3/employees/12345' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...'

   200 application/json

   {
     "id": "12345",
     "badgeNumber": "001",
     "email": "employee@example.com",
     "personalInformation": {
       "firstName": "John",
       "lastName": "Doe"
     },
     "employment": {
       "homeGroupId": "16",  
       "employmentStartDate": "2020-01-01",
       "passive": false,
       "locked": "NOT_LOCKED"
     },
     "created": "2020-01-01T10:00:00Z",
     "updated": "2023-06-01T08:30:00Z"
   }

   Here the employee sits on group 16. That is the value the rest of this guide treats as the old unit.

2. 2

   Update the employee's home unit

   Patch the employee record with the new homeGroupId.

   curl -X PATCH 'https://api.eu.quinyx.com/hr/v3/employees/12345' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' \
     -H 'Content-Type: application/json' \
     -d '{
       "employment": {
         "homeGroupId": "23"
       }
     }'

   200 application/json

   {
     "id": "12345",  
     "badgeNumber": "001",
     "email": "employee@example.com",
     "personalInformation": {
       "firstName": "John",
       "lastName": "Doe"
     },
     "employment": {
       "homeGroupId": "23",  
       "employmentStartDate": "2020-01-01",
       "passive": false,
       "locked": "NOT_LOCKED"
     },
     "created": "2020-01-01T10:00:00Z",
     "updated": "2026-04-01T09:12:44Z"
   }

   Compare this against step 1: employment.homeGroupId is now 23 and updated has moved. Nothing else changed. The role assignments returned in the next step are still attached to group 16, which is why steps 4 and 5 exist.

3. 3

   List existing role assignments

   Retrieve the employee's current role assignments to identify which ones are tied to the old group.

   curl 'https://api.eu.quinyx.com/hr/v3/role-assignments?employeeIdIn=12345' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...'

   200 application/json

   {
     "data": [
       {
         "id": "9001", 
         "employeeId": "12345",
         "groupId": "16",
         "roleId": "12",
         "startDate": "2020-01-01",  
         "created": "2020-01-01T10:00:00Z",
         "updated": "2020-01-01T10:00:00Z"
       },
       {
         "id": "9002",
         "employeeId": "12345",
         "groupId": "16",
         "roleId": "13",
         "startDate": "2023-06-01",
         "created": "2023-06-01T08:30:00Z",
         "updated": "2023-06-01T08:30:00Z"
       }
     ],
     "pagination": {
       "nextPageToken": "eyJpZCI6MTIwfQ"
     }
   }

   Note that endDate is not present on the response. Write down the id and roleId of each assignment linked to the old group. You will need them in the next two steps.

4. 4

   Terminate the old role assignments

   For each assignment on the old group, set an endDate to close it out on the day of the move.

   curl -X PATCH 'https://api.eu.quinyx.com/hr/v3/role-assignments/9001' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' \
     -H 'Content-Type: application/merge-patch+json' \
     -d '{
       "endDate": "2026-03-31"
     }'

   200 application/json

   {
     "id": "9001",  
     "employeeId": "12345",
     "groupId": "16",
     "roleId": "12",
     "startDate": "2020-01-01", 
     "endDate": "2026-03-31",  
     "created": "2020-01-01T10:00:00Z",
     "updated": "2026-04-01T09:18:03Z"
   }

   Repeat this for every assignment that should no longer be active on the old group.

5. 5

   Assign the employee to the new group

   Create a new role assignment on the destination group, using the same roleId as the terminated assignment.

   Note: Set startDate to the move date so the assignment is effective immediately. If the move is scheduled in the future, you can set a future startDate and the assignment will become active on that date.

   curl -X POST 'https://api.eu.quinyx.com/hr/v3/role-assignments' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' \
     -H 'Content-Type: application/json' \
     -d '{
       "employeeId": "12345",
       "groupId": "23",
       "roleId": "12",
       "startDate": "2026-04-01"
     }'

   201 application/json

   {
     "id": "9003",  
     "employeeId": "12345",
     "groupId": "23",
     "roleId": "12",
     "startDate": "2026-04-01",  
     "created": "2026-04-01T09:20:57Z",
     "updated": "2026-04-01T09:20:57Z"
   }

   The employee is now associated with the new unit and their role is active in the destination group.

• Create employees — see the Create Employees guide.
• Remove an assignment entirely — use DELETE /hr/v3/role-assignments/{id} instead of setting an endDate if the old assignment should be removed rather than closed out with a date.
• Update employee details — use PUT /hr/v3/employees/{id} for a full update or PATCH /hr/v3/employees/{id} for partial changes.