sprPositions

Represents a position — the job/role master record (e.g. occupation, grade) that can be assigned to an employee via an allocation.

Base URL

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

Supported operations

Operation	HTTP method	Endpoint	Description
List	GET	`/sprPositions`	Returns a collection of positions.
Get	GET	`/sprPositions({id})`	Returns a single position by its system ID.
Create	POST	`/sprPositions`	Creates a new position.
Update	PATCH	`/sprPositions({id})`	Updates an existing position.
Delete	DELETE	`/sprPositions({id})`	Deletes a position.

Properties

Property	Type	Writable	Description
`id`	Guid	No	System-generated unique identifier (OData key).
`code`	String	Yes	Unique code identifying the position. Required (`ShowMandatory`). Renaming (changing `code` on PATCH) renames the underlying position record.
`description`	String	Yes	Description of the position.
`descriptionENU`	String	No	English description of the position, resolved from the position's translation table.
`sodraPositionGroupNo`	String	Yes	Sodra position group number assigned to this position for social insurance reporting. Must match an existing code in the Sodra position groups list. Format: only English letters (A-Z, a-z), digits (0-9), a dot (`.`) and a hyphen (`-`); maximum length 15 characters.
`qualificationLevelCode`	String	Yes	Qualification level code required for this position.
`experienceLevelCode`	String	Yes	Experience level code required for this position.
`employeeProfessionCode`	String	Yes	Official employee profession classification code assigned to this position.
`employeeProfessionDesc`	String	No	Description of the employee profession classification, resolved from `employeeProfessionCode`.
`lastModifiedDateTime`	DateTimeOffset	No	Timestamp of the last modification (UTC).

Relationships / navigation properties

This page does not define any navigation properties (parts). Allocations and employees link to a position via their own positionId property; expand sprPositions from sprAllocations or sprEmployees instead of from here.

Remarks

Required fields on create: code is the only mandatory property.
Renaming a position: Changing code on PATCH renames the underlying position record rather than creating a new one; all allocations and employees referencing it via positionId keep working, but anything referencing it by positionCode only should be re-synced.
sodraPositionGroupNo format rule: Only English letters (A-Z, a-z), digits (0-9), a dot (.) and a hyphen (-) are allowed; maximum length 15 characters. An invalid character raises a field-level validation error on write. The value must also exist in the Sodra position groups list; otherwise the write fails.
Downstream propagation: qualificationLevelCode and experienceLevelCode set here are the source of truth consumed as read-only, computed values by sprEmployees (via the employee's current position) and sprAllocations (via the allocation's assigned position). Update the position to change these values; they cannot be set directly on an employee or allocation record through the API. sodraPositionGroupNo is not copied to allocations: an allocation holds its own value (entered in the UI), and sprEmployees returns the position's value only when the employee's last main allocation has none.
descriptionENU / employeeProfessionDesc: Both are read-only values resolved from related translation/profession master data; they cannot be set directly.
If-Match header: Required for PATCH to prevent mid-air collisions. Use the @odata.etag value from a prior GET, or If-Match: * to unconditionally overwrite.

Example requests

List all positions

GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprPositions

{
  "value": [
    {
      "@odata.etag": "W/\"JzE5OzE1NTg0NjQ1NDM3NjY1NDcxOTYyMTswMDsn\"",
      "id": "3e2bbeaf-381f-ee11-a396-ce5b49aea574",
      "code": "DARB01",
      "description": "Darbuotojas 01",
      "descriptionENU": "",
      "sodraPositionGroupNo": "",
      "qualificationLevelCode": "",
      "experienceLevelCode": "",
      "employeeProfessionCode": "",
      "employeeProfessionDesc": "",
      "lastModifiedDateTime": "2025-10-28T07:21:26.79Z"
    }
  ]
}

Get a single position

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

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

Create a position

POST /api/softera/softeraPayroll/v1.0/companies({companyId})/sprPositions
Content-Type: application/json

{
    "code": "DARB02",
    "description": "Darbuotojas 02",
    "sodraPositionGroupNo": "A.1-2",
    "qualificationLevelCode": "L1",
    "experienceLevelCode": "E1",
    "employeeProfessionCode": "1234"
}

Response — 201 Created — returns the created position object (same shape as Get response).

Update a position

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

{
    "description": "Darbuotojas 02 (updated)",
    "sodraPositionGroupNo": "A.1-3"
}

Response — 200 OK — returns the updated position object.

Delete a position

DELETE /api/softera/softeraPayroll/v1.0/companies({companyId})/sprPositions({id})
If-Match: *

Response — 204 No Content