Create Employees

This guide walks you through the full employee onboarding flow using the Quinyx API. You will learn how to look up an available role, create an employee record, and assign the employee to a group with that role.

1. 1

   Find the right role

   Before creating the employee, list the roles available in your organization so you can pick the right roleId for the assignment in step 3.

   curl 'https://api.eu.quinyx.com/organization/v3/roles' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...'

   200 application/json

   {
     "data": [
       {
         "id": "12",  
         "name": "Manager",
         "xrefId": "ext-role-123",
         "levelId": "5"
       },
       {
         "id": "13",
         "name": "Shift lead",
         "xrefId": "ext-role-124",
         "levelId": "3"
       }
     ],
     "pagination": {
       "nextPageToken": "eyJpZCI6MTIwfQ"
     }
   }

   Note down the id of the role you want to assign.

2. 2

   Create the employee

   Use the Employees API to create the employee record. Only a small set of fields are required.

   curl -X POST 'https://api.eu.quinyx.com/hr/v3/employees' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...' \
     -H 'Content-Type: application/json' \
     -d '{
       "badgeNumber": "001",
       "email": "employee@example.com",
       "personalInformation": {
         "firstName": "John",
         "lastName": "Doe"
       },
       "employment": {
         "homeGroupId": "16",
         "employmentStartDate": "2026-04-01"
       }
     }'

   Note: Additional fields such as address, contactInformation, emergencyContact, and punchSettings are all optional and can be provided at creation time or updated later.

   201 application/json

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

   Save the id returned in the response. You will need it in the next step.

3. 3

   Assign a role

   With the employee created, assign them to a group with the role you identified in step 1.

   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": "16",
       "roleId": "12"
     }'

   Note: startDate defaults to today if omitted. You can also set an endDate to schedule a temporary assignment. An employee can hold multiple role assignments concurrently or over time.

   201 application/json

   {
     "id": "9001",
     "employeeId": "12345",  
     "groupId": "16",  
     "roleId": "12",  
     "startDate": "2026-04-01",
     "created": "2026-04-01T10:05:12Z",
     "updated": "2026-04-01T10:05:12Z"
   }

   The employee is now active in the system and assigned to their group. The employee is also now eligible for scheduling.

Your employee is ready. From here you can:

• Update employee details using PUT /hr/v3/employees/{id} (full replacement) or PATCH /hr/v3/employees/{id} (partial update).
• Look up an employee using their badge number instead of their internal ID: GET /hr/v3/employees/badgeNumber:EMP12345.
• Terminate a role assignment by setting an endDate via PATCH /hr/v3/role-assignments/{id}.
• Delete an employee record using DELETE /hr/v3/employees/{id}.