# 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. ## Before you start - **A valid access token** ([Make your first call](/guides/getting-started)) See how to obtain one in the getting started guide. - **A token with the required scopes** Your access token needs to have following scopes available: - `hr:employees:read`: read the employee's current state (step 1) - `hr:employees:update`: patch the employee's home unit (step 2) - `hr:role-assignments:read`: list existing assignments (step 3) - `hr:role-assignments:update`: close out the old assignments (step 4) - `hr:role-assignments:create`: create the new assignment (step 5) - **The employee identifier** The employee's `id`, or their `badgeNumber`. - **The destination unit ID** The `homeGroupId` of the destination unit. You can retrieve it from `GET /organization/v3/groups`. ## 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. ```bash curl 'https://api.eu.quinyx.com/hr/v3/employees/12345' \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' ``` 200 application/json ```js 200 application/json { "id": "12345", "badgeNumber": "001", "email": "employee@example.com", "personalInformation": { "firstName": "John", "lastName": "Doe" }, "employment": { "homeGroupId": "16", // [!code highlight] "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. ## Update the employee's home unit Patch the employee record with the new `homeGroupId`. ```bash 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" // [!code highlight] } }' ``` 200 application/json ```js 200 application/json { "id": "12345", // [!code highlight] "badgeNumber": "001", "email": "employee@example.com", "personalInformation": { "firstName": "John", "lastName": "Doe" }, "employment": { "homeGroupId": "23", // [!code highlight] "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. ## List existing role assignments Retrieve the employee's current role assignments to identify which ones are tied to the old group. ```bash curl 'https://api.eu.quinyx.com/hr/v3/role-assignments?employeeIdIn=12345' \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' ``` 200 application/json ```js 200 application/json { "data": [ { "id": "9001", // [!code highlight] "employeeId": "12345", "groupId": "16", "roleId": "12", "startDate": "2020-01-01", // [!code highlight] "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. ## 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. ```bash 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" // [!code highlight] }' ``` 200 application/json ```js 200 application/json { "id": "9001", // [!code highlight] "employeeId": "12345", "groupId": "16", "roleId": "12", "startDate": "2020-01-01", // [!code highlight] "endDate": "2026-03-31", // [!code highlight] "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. ## 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. ```bash 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 ```js 201 application/json { "id": "9003", // [!code highlight] "employeeId": "12345", "groupId": "23", "roleId": "12", "startDate": "2026-04-01", // [!code highlight] "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. ## Next Steps - **Create employees** — see the [Create Employees](/guides/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.