---
title: "sprEmployees"
slug: "spremployees"
updated: 2026-10-16T13:04:40Z
published: 2026-10-16T13:04:40Z
canonical: "instrukcijos.softera.lt/spremployees"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://instrukcijos.softera.lt/llms.txt
> Use this file to discover all available pages before exploring further.

# sprEmployees

Represents an employee in the Softera Payroll system, including personal contact details, employment and termination dates, dimension assignments, and links to contracts, allocations, and personal information.

## Base URL

```
https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environmentName}/api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees
```

## Supported operations

| Operation | HTTP method | Description |
| --- | --- | --- |
| List | GET | Returns a collection of employees. |
| Get | GET | Returns a single employee by ID. |
| Create | POST | Creates a new employee. |
| Update | PATCH | Updates an existing employee. |
| Delete | DELETE | Deletes an employee. |

## Properties

| Property | Type | Writable | Description |
| --- | --- | --- | --- |
| `id` | Guid | No | System-generated unique identifier (OData key). |
| `number` | String | Yes | Employee number (code). Auto-assigned on creation if omitted. |
| `firstName` | String | Yes | Employee's first name. Required on creation. |
| `middleName` | String | Yes | Employee's middle name. |
| `surname` | String | Yes | Employee's surname. Required on creation. |
| `employmentDate` | Date | Yes | Date the employee was hired. Required on creation. |
| `terminationDate` | Date | Yes | Date the employee was terminated. Use `0001-01-01` for no termination. |
| `warningOfTerminationDate` | Date | Yes | Date the termination warning was issued. Use `0001-01-01` if not applicable. |
| `personalEMail` | String | Yes | Employee's personal e-mail address. |
| `companyEMail` | String | Yes | Employee's company e-mail address. |
| `phoneNo` | String | Yes | Employee's phone number. |
| `companyMobPhoneNo` | String | Yes | Company-issued mobile phone number. |
| `mobPhoneNo` | String | Yes | Employee's personal mobile phone number. |
| `groundsForTerminaCode` | String | Yes | Code identifying the grounds for termination. |
| `groundsForTerminaId` | Guid | Yes | System ID of the grounds-for-termination record. Use `00000000-0000-0000-0000-000000000000` when not applicable. |
| `orderOfTerminationNo` | String | Yes | Reference number of the termination order document. |
| `lengthOfServFromDate` | Date | Yes | Start date used when calculating the employee's length of service (seniority). Use `0001-01-01` if not set. |
| `positionCode` | String | No | Code of the employee's current position. Computed via `SetAutoCalcFields`. |
| `positionId` | Guid | No | System ID of the employee's current position. Computed via `SetAutoCalcFields`. |
| `qualificationLevelCode` | String | No | Qualification level code of the employee's current position. Computed via `SetAutoCalcFields`, resolved from the position's `qualificationLevelCode`. |
| `experienceLevelCode` | String | No | Experience level code of the employee's current position. Computed via `SetAutoCalcFields`, resolved from the position's `experienceLevelCode`. |
| `sodraPositionGroupNo` | String | No | Sodra position group number of the employee's last main allocation. If the allocation has none, the number of its position is returned. Computed on read. Format: only English letters (A-Z, a-z), digits (0-9), a dot (`.`) and a hyphen (`-`); maximum length 15 characters. |
| `integrationNo` | String | Yes | External reference number used for third-party integrations. |
| `ePIntegrationLogin` | String | Yes | Login identifier used for the Employee Portal (EP / HiBob) integration. Maps to `SPR EP Integration Login` on the employee record. |
| `globalDim1Code` | String | Yes | Global Dimension 1 code. |
| `globalDim1Name` | String | No | Display name of Global Dimension 1. Read-only; resolved from `globalDim1Code`. |
| `globalDim2Code` | String | Yes | Global Dimension 2 code. |
| `globalDim2Name` | String | No | Display name of Global Dimension 2. |
| `globalDim3Code` | String | Yes | Global Dimension 3 code. |
| `globalDim3Name` | String | No | Display name of Global Dimension 3. |
| `globalDim4Code` | String | Yes | Global Dimension 4 code. |
| `globalDim4Name` | String | No | Display name of Global Dimension 4. |
| `globalDim5Code` | String | Yes | Global Dimension 5 code. |
| `globalDim5Name` | String | No | Display name of Global Dimension 5. |
| `globalDim6Code` | String | Yes | Global Dimension 6 code. |
| `globalDim6Name` | String | No | Display name of Global Dimension 6. |
| `globalDim7Code` | String | Yes | Global Dimension 7 code. |
| `globalDim7Name` | String | No | Display name of Global Dimension 7. |
| `globalDim8Code` | String | Yes | Global Dimension 8 code. |
| `globalDim8Name` | String | No | Display name of Global Dimension 8. |
| `skipSPREmplPersonalInfoAutoCreation` | Boolean | Yes | When `true` on POST, suppresses automatic creation of the linked `sprEmplPersonalInformation` record. Has no effect on PATCH. |
| `lastModifiedDateTime` | DateTimeOffset | No | Timestamp of the last modification (UTC). |

## Relationships / navigation properties

| Navigation property | Multiplicity | Related entity set | Description |
| --- | --- | --- | --- |
| `sprDimensionSetLines` | Many | `sprDimensionSetLines` | Dimension set lines linked to this employee. Read-only; expand to retrieve. |
| `sprEmplPersonalInformation` | ZeroOrOne | `sprEmplPersonalInformations` | Employee personal information record (personal ID, address, document details, etc.). |
| `sprContracts` | Many | `sprContracts` | Employment contracts for this employee. Supports deep insert. |
| `sprAllocations` | Many | `sprAllocations` | All allocations linked directly to this employee (flattened view across all contracts). |
| `sprPositions` | ZeroOrOne | `sprPositions` | The employee's current position record, resolved via `positionId`. |
| `sprRelatives` | Many | `sprRelatives` | Relatives registered for the employee. |
| `sprPaymentLocations` | Many | `sprPaymentLocations` | Bank account / payment location records for the employee. |

You can expand navigation properties using the `$expand` query parameter. Nested `$filter` and `$select` are supported within `$expand`.

## Remarks

- **Required fields on POST**: `firstName`, `surname`, and `employmentDate` are the minimum required properties. All other writable fields are optional and default to empty values.
- **Auto-assigned `number`**: If `number` is omitted on POST, the system assigns the next available employee number automatically.
- **Empty dates**: The API uses `0001-01-01` to represent an empty (null) date. Do not send a JSON `null` for date fields.
- **Optimistic concurrency on PATCH**: The `If-Match` header is required. Use `If-Match: *` to unconditionally overwrite, or supply the `@odata.etag` value from a prior GET to enforce concurrency checking.
- **`skipSPREmplPersonalInfoAutoCreation`**: When set to `false` (default) on POST, the server automatically creates a linked `sprEmplPersonalInformation` record. Set to `true` to suppress this behaviour, for example when you intend to create the personal information record yourself in a subsequent request.
- **`positionCode` / `positionId` / `qualificationLevelCode` / `experienceLevelCode`**: These are computed fields resolved via `SetAutoCalcFields` at page open. They reflect the employee's active position from the linked position record and cannot be set directly on the employee — assign positions via the allocation (`sprAllocations`), and edit the underlying values on the position (`sprPositions`).
- **`sodraPositionGroupNo`**: Read-only and computed on read. The value is taken from the employee's last main allocation (`sprAllocations`); if the allocation has none, the value of its position (`sprPositions`) is returned instead.
- **`globalDimNName` fields** (e.g. `globalDim1Name`): These are read-only display values derived from the corresponding `globalDimNCode`. Submit the code to change a dimension; the name will be resolved server-side.
- **Deep insert**: You can create an employee together with its contracts and allocations in a single POST request by appending `?$expand=sprContracts($expand=sprAllocations)` and nesting the child objects in the request body. See the example below.
- **Filtered expand for effective allocations**: To retrieve only the allocations effective on a given date, use a nested `$filter` inside `$expand`:

```
$expand=sprContracts($expand=sprAllocations($filter=startDate le 2025-10-02))
```
- **Change tracking**: The entity set supports OData change tracking (`ChangeTrackingAllowed = true`).
- **OData key**: The OData key field is `SystemId` (exposed as `id`). Use the `id` GUID value in the URL path to address individual records.

## Example requests

### List all employees

```
GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees
Accept-Language: lt-LT
```

```
{
  "value": [
    {
      "@odata.etag": "W/\"JzIwOzE1NTg0NjQ1NDM3NjY1NDcxOTYyMTswMDsn\"",
      "id": "71db4ca9-ceb3-f011-be4a-84a5d7ca2b0b",
      "number": "D0003",
      "firstName": "Trečias",
      "middleName": "",
      "surname": "Trečiokas",
      "employmentDate": "2025-09-01",
      "terminationDate": "0001-01-01",
      "warningOfTerminationDate": "0001-01-01",
      "personalEMail": "",
      "companyEMail": "",
      "phoneNo": "",
      "companyMobPhoneNo": "",
      "mobPhoneNo": "",
      "groundsForTerminaCode": "",
      "groundsForTerminaId": "00000000-0000-0000-0000-000000000000",
      "orderOfTerminationNo": "",
      "lengthOfServFromDate": "0001-01-01",
      "positionCode": "",
      "positionId": "00000000-0000-0000-0000-000000000000",
      "qualificationLevelCode": "",
      "experienceLevelCode": "",
      "sodraPositionGroupNo": "",
      "integrationNo": "",
      "ePIntegrationLogin": "",
      "globalDim1Code": "",
      "globalDim1Name": "",
      "globalDim2Code": "",
      "globalDim2Name": "",
      "globalDim3Code": "",
      "globalDim3Name": "",
      "globalDim4Code": "",
      "globalDim4Name": "",
      "globalDim5Code": "",
      "globalDim5Name": "",
      "globalDim6Code": "",
      "globalDim6Name": "",
      "globalDim7Code": "",
      "globalDim7Name": "",
      "globalDim8Code": "",
      "globalDim8Name": "",
      "skipSPREmplPersonalInfoAutoCreation": false,
      "lastModifiedDateTime": "2025-10-28T07:21:26.79Z"
    }
  ]
}
```

---

### Get a single employee

```
GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees({id})
```

Response body is the same structure as a single item in the list above (HTTP 200).

---

### Get a single employee with expanded navigation properties

You can expand `sprEmplPersonalInformation`, `sprDimensionSetLines`, `sprContracts`, and nested `sprAllocations` in one request:

```
GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees({id})?$expand=sprEmplPersonalInformation,sprDimensionSetLines,sprContracts($expand=sprAllocations($filter=startDate le 2025-10-02))
```

```
{
  "@odata.etag": "W/\"JzIwOzE1NTg0NjQ1NDM3NjY1NDcxOTYyMTswMDsn\"",
  "id": "71db4ca9-ceb3-f011-be4a-84a5d7ca2b0b",
  "number": "D0003",
  "firstName": "Trečias",
  "middleName": "",
  "surname": "Trečiokas",
  "employmentDate": "2025-09-01",
  "terminationDate": "0001-01-01",
  "warningOfTerminationDate": "0001-01-01",
  "personalEMail": "",
  "companyEMail": "",
  "phoneNo": "",
  "companyMobPhoneNo": "",
  "mobPhoneNo": "",
  "groundsForTerminaCode": "",
  "groundsForTerminaId": "00000000-0000-0000-0000-000000000000",
  "orderOfTerminationNo": "",
  "lengthOfServFromDate": "0001-01-01",
  "ePIntegrationLogin": "",
  "globalDim1Code": "",
  "globalDim1Name": "",
  "globalDim2Code": "",
  "globalDim2Name": "",
  "skipSPREmplPersonalInfoAutoCreation": false,
  "lastModifiedDateTime": "2025-10-28T07:21:26.79Z",
  "sprDimensionSetLines": [],
  "sprEmplPersonalInformation": {
    "@odata.etag": "W/\"JzIwOzE3MDAyOTMxODM2Mzg3MjA4NjUwMTswMDsn\"",
    "id": "73db4ca9-ceb3-f011-be4a-84a5d7ca2b0b",
    "employeeNumber": "D0003",
    "employeeId": "71db4ca9-ceb3-f011-be4a-84a5d7ca2b0b",
    "personalNo": "",
    "dateOfBirth": "0001-01-01",
    "gender": " ",
    "lastModifiedDateTime": "2025-10-28T07:21:04.723Z"
  },
  "sprContracts": [
    {
      "@odata.etag": "W/\"JzE5OzIxMDk4OTcwOTk3NzQ3NTQ3NzcxOzAwOyc=\"",
      "id": "d2b85cc4-ceb3-f011-be4a-84a5d7ca2b0b",
      "employeeNumber": "D0003",
      "employeeId": "71db4ca9-ceb3-f011-be4a-84a5d7ca2b0b",
      "number": "S0002",
      "startDate": "2025-09-01",
      "endDate": "0001-01-01",
      "contractType": "Open-Ended",
      "lastModifiedDateTime": "2025-10-28T07:21:49.82Z",
      "sprAllocations": [
        {
          "positionId": "abd17761-35b3-f011-be4a-84a5d7ca2b0b",
          "positionCode": "DEFAULT",
          "positionDescription": "Default"
        }
      ]
    }
  ]
}
```

---

### Create an employee (minimum fields)

```
POST /api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees
Content-Type: application/json
Accept-Language: lt-LT
```

```
{
  "firstName": "API First Name",
  "surname": "API Surname",
  "employmentDate": "2023-05-01"
}
```

**Response — 201 Created**

```
{
  "@odata.etag": "W/\"JzE5OzI5ODg2MTAwMTk1Mjc0NTM3MDExOzAwOyc=\"",
  "id": "26b91b4f-0d27-ee11-a395-fe66e2afdfa9",
  "number": "D0016",
  "firstName": "API First Name",
  "middleName": "",
  "surname": "API Surname",
  "employmentDate": "2023-05-01",
  "terminationDate": "0001-01-01",
  "warningOfTerminationDate": "0001-01-01",
  "personalEMail": "",
  "companyEMail": "",
  "companyMobPhoneNo": "",
  "mobPhoneNo": "",
  "groundsForTerminaCode": "",
  "groundsForTerminaId": "00000000-0000-0000-0000-000000000000",
  "orderOfTerminationNo": "",
  "lengthOfServFromDate": "0001-01-01",
  "skipSPREmplPersonalInfoAutoCreation": false,
  "lastModifiedDateTime": "2023-07-20T14:54:22.05Z"
}
```

---

### Create an employee (all fields)

```
POST /api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees
Content-Type: application/json
Accept-Language: lt-LT
```

```
{
  "firstName": "API First Name",
  "middleName": "",
  "surname": "API Surname",
  "employmentDate": "2023-05-01",
  "terminationDate": "0001-01-01",
  "warningOfTerminationDate": "0001-01-01",
  "personalEMail": "aaa@ggg.com",
  "companyEMail": "aaa@softera.lt",
  "companyMobPhoneNo": "866612345",
  "mobPhoneNo": "",
  "groundsForTerminaId": "00000000-0000-0000-0000-000000000000",
  "orderOfTerminationNo": "",
  "lengthOfServFromDate": "2020-06-01",
  "skipSPREmplPersonalInfoAutoCreation": false
}
```

**Response — 201 Created**

```
{
  "@odata.etag": "W/\"JzE5Ozc4NjE5MTcxNTAwMTY4NzYyMjcxOzAwOyc=\"",
  "id": "1ebc8180-0d27-ee11-a395-fe66e2afdfa9",
  "number": "D0017",
  "firstName": "API First Name",
  "middleName": "",
  "surname": "API Surname",
  "employmentDate": "2023-05-01",
  "terminationDate": "0001-01-01",
  "warningOfTerminationDate": "0001-01-01",
  "personalEMail": "aaa@ggg.com",
  "companyEMail": "aaa@softera.lt",
  "companyMobPhoneNo": "866612345",
  "mobPhoneNo": "",
  "groundsForTerminaCode": "",
  "groundsForTerminaId": "00000000-0000-0000-0000-000000000000",
  "orderOfTerminationNo": "",
  "lengthOfServFromDate": "2020-06-01",
  "skipSPREmplPersonalInfoAutoCreation": false,
  "lastModifiedDateTime": "2023-07-20T14:55:44.937Z"
}
```

---

### Create an employee with contract and allocation (deep insert)

Include `$expand=sprContracts($expand=sprAllocations)` in the URL and provide nested objects in the request body.

```
POST /api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees?$expand=sprContracts($expand=sprAllocations)
Content-Type: application/json
Accept-Language: lt-LT
```

```
{
  "firstName": "API First Name",
  "middleName": "",
  "surname": "API Surname",
  "employmentDate": "2023-05-01",
  "personalEMail": "aaa@ggg.com",
  "companyEMail": "aaa@softera.lt",
  "companyMobPhoneNo": "866612345",
  "lengthOfServFromDate": "2020-06-01",
  "sprContracts": [
    {
      "startDate": "2023-05-01",
      "contractType": "Open-Ended",
      "signDate": "2023-05-01",
      "probationPeriodFrom": "2023-05-01",
      "probationPeriod": "3M",
      "sprAllocations": [
        {
          "startDate": "2023-05-01",
          "endDate": "0001-01-01",
          "positionId": "{positionId}",
          "emplPostGroupId": "{employeePostingGroupId}",
          "workScheduleFormulaId": "{workScheduleFormulaId}",
          "staff": 1,
          "vacationScheme": 20,
          "tEAType": "Apply"
        }
      ]
    }
  ]
}
```

**Response — 201 Created** (structure identical to create, with the `sprContracts` array populated in the response body).

---

### Update an employee

```
PATCH /api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees({id})
Content-Type: application/json
If-Match: *
```

```
{
  "number": "API001",
  "firstName": "API Pirmas",
  "middleName": "",
  "surname": "API Pirmokas",
  "employmentDate": "2022-06-01",
  "terminationDate": "0001-01-01",
  "warningOfTerminationDate": "0001-01-01",
  "personalEMail": "aaabbb@gg.com",
  "companyEMail": "001@softera.lt",
  "companyMobPhoneNo": "866612345",
  "mobPhoneNo": "",
  "groundsForTerminaCode": "",
  "orderOfTerminationNo": "",
  "lengthOfServFromDate": "2020-06-01"
}
```

**Response — 200 OK** (returns the full updated employee object).

---

### Delete an employee

```
DELETE /api/softera/softeraPayroll/v1.0/companies({companyId})/sprEmployees({id})
```

**Response — 204 No Content**