{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["prerequisites","prerequisite","numbered-list","numbered-item","code-snippet"]},"redocly_category":"Guides","type":"markdown"},"seo":{"title":"Move Employee","description":"Quinyx Developer Portal: official API documentation for integrating workforce management, scheduling, and HR data through our REST APIs.","siteUrl":"https://developer.quinyx.com","projectTitle":"Quinyx","image":"/assets/quinyx-image-share-preview.923e4c9034df4fc24c974ff2fc606f3643bcf7d3a3643cef3e6df941da353c5a.925ff8b2.png","keywords":"documentation, api","lang":"en-US","jsonLd":{"@context":"https://schema.org","@type":"Organization","name":"Quinyx","url":"https://www.quinyx.com","logo":"https://developer.quinyx.com/static/logo.svg","sameAs":["https://www.linkedin.com/company/quinyx","https://github.com/quinyx"]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"move-employee","__idx":0},"children":["Move Employee"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Prerequisites","attributes":{"title":"Before you start","count":4},"children":[{"$$mdtype":"Tag","name":"Prerequisite","attributes":{"title":"A valid access token","icon":"key","href":"/guides/getting-started","action":"Make your first call"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See how to obtain one in the getting started guide."]}]},{"$$mdtype":"Tag","name":"Prerequisite","attributes":{"title":"A token with the required scopes","icon":"tag"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your access token needs to have following scopes available:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hr:employees:read"]},": read the employee's current state (step 1)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hr:employees:update"]},": patch the employee's home unit (step 2)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hr:role-assignments:read"]},": list existing assignments (step 3)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hr:role-assignments:update"]},": close out the old assignments (step 4)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hr:role-assignments:create"]},": create the new assignment (step 5)"]}]}]},{"$$mdtype":"Tag","name":"Prerequisite","attributes":{"title":"The employee identifier","icon":"id-badge"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The employee's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", or their ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["badgeNumber"]},"."]}]},{"$$mdtype":"Tag","name":"Prerequisite","attributes":{"title":"The destination unit ID","icon":"sitemap"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["homeGroupId"]}," of the destination unit. You can retrieve it from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /organization/v3/groups"]},"."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"NumberedList","attributes":{"type":"number","size":"medium"},"children":[{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["Read the employee's current state"],"anchorId":"read-the-employees-current-state","headlineLevel":2,"type":"number","size":"medium","index":1,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fetch the employee before you change anything. This gives you the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-1-get-employee-request.sh","language":"bash","header":{"controls":{"copy":{}}},"lang":"bash","source":"curl 'https://api.eu.quinyx.com/hr/v3/employees/12345' \\\n  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...'\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-1-get-employee-response.js","language":"js","title":"200 application/json","header":{"title":"200 application/json","controls":{"copy":{}}},"lang":"js","source":"{\n  \"id\": \"12345\",\n  \"badgeNumber\": \"001\",\n  \"email\": \"employee@example.com\",\n  \"personalInformation\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\"\n  },\n  \"employment\": {\n    \"homeGroupId\": \"16\",  // [!code highlight]\n    \"employmentStartDate\": \"2020-01-01\",\n    \"passive\": false,\n    \"locked\": \"NOT_LOCKED\"\n  },\n  \"created\": \"2020-01-01T10:00:00Z\",\n  \"updated\": \"2023-06-01T08:30:00Z\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here the employee sits on group ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["16"]},". That is the value the rest of this guide treats as the old unit."]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["Update the employee's home unit"],"anchorId":"update-the-employees-home-unit","headlineLevel":2,"type":"number","size":"medium","index":2,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Patch the employee record with the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["homeGroupId"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-2-home-unit-request.sh","language":"bash","header":{"controls":{"copy":{}}},"lang":"bash","source":"curl -X PATCH 'https://api.eu.quinyx.com/hr/v3/employees/12345' \\\n  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"employment\": {\n      \"homeGroupId\": \"23\"  // [!code highlight]\n    }\n  }'\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-2-home-unit-response.js","language":"js","title":"200 application/json","header":{"title":"200 application/json","controls":{"copy":{}}},"lang":"js","source":"{\n  \"id\": \"12345\",  // [!code highlight]\n  \"badgeNumber\": \"001\",\n  \"email\": \"employee@example.com\",\n  \"personalInformation\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\"\n  },\n  \"employment\": {\n    \"homeGroupId\": \"23\",  // [!code highlight]\n    \"employmentStartDate\": \"2020-01-01\",\n    \"passive\": false,\n    \"locked\": \"NOT_LOCKED\"\n  },\n  \"created\": \"2020-01-01T10:00:00Z\",\n  \"updated\": \"2026-04-01T09:12:44Z\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Compare this against step 1: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["employment.homeGroupId"]}," is now ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["23"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated"]}," has moved. Nothing else changed. The role assignments returned in the next step are still attached to group ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["16"]},", which is why steps 4 and 5 exist."]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["List existing role assignments"],"anchorId":"list-existing-role-assignments","headlineLevel":2,"type":"number","size":"medium","index":3,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the employee's current role assignments to identify which ones are tied to the old group."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-3-role-assignments-request.sh","language":"bash","header":{"controls":{"copy":{}}},"lang":"bash","source":"curl 'https://api.eu.quinyx.com/hr/v3/role-assignments?employeeIdIn=12345' \\\n  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...'\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-3-role-assignments-response.js","language":"js","title":"200 application/json","header":{"title":"200 application/json","controls":{"copy":{}}},"lang":"js","source":"{\n  \"data\": [\n    {\n      \"id\": \"9001\", // [!code highlight]\n      \"employeeId\": \"12345\",\n      \"groupId\": \"16\",\n      \"roleId\": \"12\",\n      \"startDate\": \"2020-01-01\",  // [!code highlight]\n      \"created\": \"2020-01-01T10:00:00Z\",\n      \"updated\": \"2020-01-01T10:00:00Z\"\n    },\n    {\n      \"id\": \"9002\",\n      \"employeeId\": \"12345\",\n      \"groupId\": \"16\",\n      \"roleId\": \"13\",\n      \"startDate\": \"2023-06-01\",\n      \"created\": \"2023-06-01T08:30:00Z\",\n      \"updated\": \"2023-06-01T08:30:00Z\"\n    }\n  ],\n  \"pagination\": {\n    \"nextPageToken\": \"eyJpZCI6MTIwfQ\"\n  }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDate"]}," is not present on the response. Write down the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["roleId"]}," of each assignment linked to the old group. You will need them in the next two steps."]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["Terminate the old role assignments"],"anchorId":"terminate-the-old-role-assignments","headlineLevel":2,"type":"number","size":"medium","index":4,"isLast":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For each assignment on the old group, set an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDate"]}," to close it out on the day of the move."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-4-terminate-assignment-request.sh","language":"bash","header":{"controls":{"copy":{}}},"lang":"bash","source":"curl -X PATCH 'https://api.eu.quinyx.com/hr/v3/role-assignments/9001' \\\n  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' \\\n  -H 'Content-Type: application/merge-patch+json' \\\n  -d '{\n    \"endDate\": \"2026-03-31\"  // [!code highlight]\n  }'\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-4-terminate-assignment-response.js","language":"js","title":"200 application/json","header":{"title":"200 application/json","controls":{"copy":{}}},"lang":"js","source":"{\n  \"id\": \"9001\",  // [!code highlight]\n  \"employeeId\": \"12345\",\n  \"groupId\": \"16\",\n  \"roleId\": \"12\",\n  \"startDate\": \"2020-01-01\", // [!code highlight]\n  \"endDate\": \"2026-03-31\",  // [!code highlight]\n  \"created\": \"2020-01-01T10:00:00Z\",\n  \"updated\": \"2026-04-01T09:18:03Z\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Repeat this for every assignment that should no longer be active on the old group."]}]},{"$$mdtype":"Tag","name":"NumberedItem","attributes":{"headline":["Assign the employee to the new group"],"anchorId":"assign-the-employee-to-the-new-group","headlineLevel":2,"type":"number","size":"medium","index":5,"isLast":true},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a new role assignment on the destination group, using the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["roleId"]}," as the terminated assignment."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," ","Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDate"]}," to the move date so the assignment is effective immediately. If the move is scheduled in the future, you can set a future ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDate"]}," and the assignment will become active on that date."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-5-new-assignment-request.sh","language":"bash","header":{"controls":{"copy":{}}},"lang":"bash","source":"curl -X POST 'https://api.eu.quinyx.com/hr/v3/role-assignments' \\\n  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"employeeId\": \"12345\",\n    \"groupId\": \"23\",\n    \"roleId\": \"12\",\n    \"startDate\": \"2026-04-01\"\n  }'\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"./code-examples/move-employee-5-new-assignment-response.js","language":"js","title":"201 application/json","header":{"title":"201 application/json","controls":{"copy":{}}},"lang":"js","source":"{\n  \"id\": \"9003\",  // [!code highlight]\n  \"employeeId\": \"12345\",\n  \"groupId\": \"23\",\n  \"roleId\": \"12\",\n  \"startDate\": \"2026-04-01\",  // [!code highlight]\n  \"created\": \"2026-04-01T09:20:57Z\",\n  \"updated\": \"2026-04-01T09:20:57Z\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The employee is now associated with the new unit and their role is active in the destination group."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":1},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create employees"]}," — see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/create-employees"},"children":["Create Employees"]}," guide."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Remove an assignment entirely"]}," — use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /hr/v3/role-assignments/{id}"]}," instead of setting an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDate"]}," if the old assignment should be removed rather than closed out with a date."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update employee details"]}," — use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /hr/v3/employees/{id}"]}," for a full update or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /hr/v3/employees/{id}"]}," for partial changes."]}]}]},"headings":[{"value":"Move Employee","id":"move-employee","depth":1},{"value":"Read the employee's current state","id":"read-the-employees-current-state","depth":2},{"value":"Update the employee's home unit","id":"update-the-employees-home-unit","depth":2},{"value":"List existing role assignments","id":"list-existing-role-assignments","depth":2},{"value":"Terminate the old role assignments","id":"terminate-the-old-role-assignments","depth":2},{"value":"Assign the employee to the new group","id":"assign-the-employee-to-the-new-group","depth":2},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Move Employee"}},"lastModified":"2026-09-09T17:11:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/move-employee","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}