# 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.

## Prerequisites

Before you begin, make sure you have:

- A valid access token. See [Authentication](/api/v3/authentication) for details.
- The `homeGroupId` of the unit the employee belongs to. You can retrieve it from `GET /organization/v3/groups`.
- The employee's `employmentStartDate`.


## 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.

```shell curl
curl -i -X GET \
  https://api.eu.quinyx.com/organization/v3/roles \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
```

### Response

```json 200 application/json
{
  "data": [
    {
      "id": "42",
      "name": "Manager",
      "xrefId": "ext-role-123",
      "levelId": "5"
    }
  ],
  "pagination": {
    "nextPageToken": "eyJpZCI6MTIwfQ",
    "previousPageToken": "eyJpZCI6ODB9"
  }
}
```

```json 400 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid or malformed",
  "instance": "/organization/v3/roles"
}
```

```json 401 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Access token not set or invalid, and the requested resource could not be returned",
  "instance": "/organization/v3/roles"
}
```

```json 403 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The resource could not be returned as the requestor is not authorized",
  "instance": "/organization/v3/roles"
}
```

```json 500 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/server-error",
  "title": "Server Error",
  "status": 500,
  "detail": "The server encountered an unexpected error",
  "instance": "/organization/v3/roles"
}
```

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

## 2. Create the employee

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

```shell curl
curl -i -X POST \
  https://api.eu.quinyx.com/hr/v3/employees \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "badgeNumber": "001",
    "email": "employee@example.com",
    "personalInformation": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-01-01",
      "gender": "MALE",
      "socialSecurityNumber": "000000-0000",
      "pictureURL": "https://example.com/pictures/placeholder.jpg"
    },
    "contactInformation": {
      "mobileNumber": "+46700000000",
      "phoneNumber": "+46800000000"
    },
    "address": {
      "address1": "123 Example Street",
      "address2": "Apt 1",
      "zip": "SE-10000",
      "city": "Stockholm",
      "country": "Sweden"
    },
    "employment": {
      "homeGroupId": "123",
      "staffCategoryId": "123",
      "managerId": "1234",
      "passive": false,
      "locked": "NOT_LOCKED",
      "employmentStartDate": "2020-01-01",
      "employmentEndDate": "2025-12-31",
      "industryStartDate": "2015-01-01",
      "costCentreId": "1234"
    },
    "emergencyContact": {
      "nextOfKinName": "John Doe",
      "nextOfKinPhone": "+46700000000",
      "legalGuardianName": "Jane Doe",
      "legalGuardianEmail": "guardian@example.com"
    },
    "punchSettings": {
      "allowAttestOfOwnPunches": false
    }
  }'
```

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


### Response

```json 201 application/json
{
  "id": "12345",
  "badgeNumber": "001",
  "email": "employee@example.com",
  "personalInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-01",
    "gender": "MALE",
    "socialSecurityNumber": "000000-0000",
    "pictureURL": "https://example.com/pictures/placeholder.jpg"
  },
  "contactInformation": {
    "mobileNumber": "+46700000000",
    "phoneNumber": "+46800000000"
  },
  "address": {
    "address1": "123 Example Street",
    "address2": "Apt 1",
    "zip": "SE-10000",
    "city": "Stockholm",
    "country": "Sweden"
  },
  "employment": {
    "homeGroupId": "123",
    "staffCategoryId": "123",
    "passive": false,
    "locked": "NOT_LOCKED",
    "employmentStartDate": "2020-01-01",
    "industryStartDate": "2015-01-01",
    "managerId": "1234",
    "employmentEndDate": "2025-12-31",
    "costCentreId": "1234"
  },
  "emergencyContact": {
    "nextOfKinName": "John Doe",
    "nextOfKinPhone": "+46700000000",
    "legalGuardianName": "Jane Doe",
    "legalGuardianEmail": "guardian@example.com"
  },
  "punchSettings": {
    "allowAttestOfOwnPunches": false
  },
  "updated": "2024-06-01T10:00:00Z",
  "created": "2024-06-01T10:00:00Z"
}
```

```json 400 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid or malformed",
  "instance": "/hr/v3/employees"
}
```

```json 401 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Access token not set or invalid, and the requested resource could not be returned",
  "instance": "/hr/v3/employees"
}
```

```json 403 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The resource could not be returned as the requestor is not authorized",
  "instance": "/hr/v3/employees"
}
```

```json 500 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/server-error",
  "title": "Server Error",
  "status": 500,
  "detail": "The server encountered an unexpected error",
  "instance": "/hr/v3/employees"
}
```

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

## 3. Assign a role

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

```shell curl
curl -i -X POST \
  https://api.eu.quinyx.com/hr/v3/role-assignments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "employeeId": "10",
    "groupId": "10",
    "roleId": "10",
    "startDate": "2025-10-01",
    "endDate": "2026-01-01"
  }'
```

> **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.


### Response

```json 201 application/json
{
  "id": "12345",
  "employeeId": "12345",
  "groupId": "16",
  "roleId": "12",
  "startDate": "2025-10-01",
  "endDate": "2026-12-31",
  "created": "2025-10-01T14:18:41Z",
  "updated": "2025-10-16T09:34:27Z"
}
```

```json 400 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid or malformed",
  "instance": "/hr/v3/role-assignments"
}
```

```json 401 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Access token not set or invalid, and the requested resource could not be returned",
  "instance": "/hr/v3/role-assignments"
}
```

```json 403 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The resource could not be returned as the requestor is not authorized",
  "instance": "/hr/v3/role-assignments"
}
```

```json 404 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource was not found",
  "instance": "/hr/v3/role-assignments"
}
```

```json 500 application/problem+json
{
  "type": "https://developer.quinyx.com/api/problems/server-error",
  "title": "Server Error",
  "status": 500,
  "detail": "The server encountered an unexpected error",
  "instance": "/hr/v3/role-assignments"
}
```

The employee is now active in the system and assigned to their group.

## Next Steps

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}`.