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

Properties

Relationships / navigation properties

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