sprAllocations

Represents an allocation — the assignment of an employee to a position, posting group, and work schedule within a contract, for a given date range.

Base URL

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

Supported operations

Properties

Relationships / navigation properties

You can expand navigation properties using the $expand query parameter.

Remarks

• Required fields on create: employeeNumber and wScheduleFormulaCode are marked mandatory on the page. startDate is also required in practice to create a meaningful allocation. Supply either the GUID (*Id) or the code/number (*Code, *Number) for employee, contract, position, posting group, manager, and work schedule formula references — not both.
• First allocation vs. subsequent allocations: Use a plain POST /sprAllocations for an employee's first allocation on a contract. For every subsequent allocation (a change effective from a later date), use the newUsingCurrent bound action on the employee's current allocation instead of a plain POST — this ensures field values are carried forward correctly and the allocation chain (lastContractSeqAllocation) stays consistent.
• newUsingCurrent bound action: Call POST /sprAllocations({id})/Microsoft.NAV.newUsingCurrent with body { "newDate": "YYYY-MM-DD" }, where {id} is the current allocation's id. The server creates a new allocation effective from newDate, copying field values (including the salary record) from the source allocation. If the new id is not returned, re-query the allocations for the same employee/contract (e.g. $filter=employeeId eq {employeeId}&$orderby=startDate desc) to find it.
• previousAllocationId [BETA]: An alternative way to copy field values from a specific prior allocation on create, instead of relying on the contract's last allocation. Marked should never be used in the current Postman collection — prefer newUsingCurrent for chaining allocations. Not returned populated for allocations created without it (reads back as 00000000-0000-0000-0000-000000000000).
• Deep insert — allocation with salary: You can create an allocation together with its sprAllocationSalaries record in a single POST by appending ?$expand=sprAllocationSalaries and setting skipSPRAllocationSalaryAutoCreation to true together with a nested sprAllocationSalaries object. If you omit the nested object and leave skipSPRAllocationSalaryAutoCreation at its default (false), the server automatically creates a default salary record instead.
• qualificationLevelCode / experienceLevelCode / employeeProfessionCode: These fields are copied from the assigned position (via positionId/positionCode) and are read-only on this API. To change them, update the position (sprPositions) directly, or re-assign a different positionId/positionCode on the allocation.
• sodraPositionGroupNo: Read-only on this API. The value is entered on the allocation card in the UI and is not copied from the position, so it is empty unless set there. When it is empty, sprEmployees returns the position's value instead.
• sodraPositionGroupNo format rule: only English letters (A-Z, a-z), digits (0-9), a dot (.) and a hyphen (-) are allowed; maximum length 15 characters.
• fte vs. staff: staff is obsolete; use fte. Both map to the same underlying value, 0–2 where 1 = 100%.
• pensionAccumMethod: Obsolete; retained for backward compatibility only.
• refillWScheduleEntries / deleteWScheduleEntries: Both require dateFrom and dateTo in the request body and act on the Work Schedule entries of the allocation's employee/contract/allocation combination for that date range. refillWScheduleEntries clears and regenerates entries from the work schedule formula; deleteWScheduleEntries only clears them.
• If-Match header: Required for PATCH and DELETE to prevent mid-air collisions. Use the @odata.etag value from a prior GET, or If-Match: * to unconditionally overwrite.
• Filtering by employee: Use $filter=employeeId eq {employeeId} (or employeeNumber eq {employeeNumber}) combined with $orderby=startDate desc or $orderby=number desc to retrieve an employee's allocation history, most recent first.
• $select with $expand: $select and $expand can be combined, e.g. to return only a handful of fields per allocation while still expanding sprAllocationSalaries.

Example requests

List all allocations

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

List allocations for a specific employee, most recent first

GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations?$filter=employeeId eq {employeeId}&$orderby=startDate desc

List allocations for a specific employee with a reduced field set

GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations?$filter=employeeId eq {employeeId}&$select=id,employeeNumber,employeeId,number,startDate,endDate&$orderby=number desc

List allocations for a specific employee, selected fields, with expanded salary

GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations?$filter=employeeId eq {employeeId}&$select=id,employeeNumber,employeeId,contractId,number,startDate,endDate&$orderby=number desc&$expand=sprAllocationSalaries

Get a single allocation, with expanded salary

GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations({id})?$expand=sprAllocationSalaries

Get a single allocation, with expanded dimension set lines and salary

GET /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations({id})?$expand=sprDimensionSetLines,sprAllocationSalaries

Create the first allocation of a contract

POST /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations?$expand=sprAllocationSalaries
Content-Type: application/json

{
    "contractId": "{contractId}",
    "startDate": "2023-07-19",
    "endDate": "0001-01-01",
    "positionId": "{positionId}",
    "emplPostGroupId": "{employeePostingGroupId}",
    "workScheduleFormulaId": "{workScheduleFormulaId}",
    "fte": 1,
    "vacationScheme": 20,
    "tEAType": "Apply",
    "skipSPRAllocationSalaryAutoCreation": false
}

Response — 201 Created

{
    "@odata.etag": "W/\"JzE5Ozg1MzMwNjA5MTAyMzMyNzQ1MjAxOzAwOyc=\"",
    "id": "505b2a47-162a-ee11-a395-fe66e2afdfa9",
    "previousAllocationId": "00000000-0000-0000-0000-000000000000",
    "employeeId": "a102cb47-1e27-ee11-a395-fe66e2afdfa9",
    "employeeNumber": "D0019",
    "contractId": "a302cb47-1e27-ee11-a395-fe66e2afdfa9",
    "contractNumber": "S0006",
    "number": 20,
    "lastContractSeqAllocation": true,
    "startDate": "2023-07-19",
    "endDate": "0001-01-01",
    "positionId": "3e2bbeaf-381f-ee11-a396-ce5b49aea574",
    "positionCode": "DARB01",
    "positionDescription": "Darbuotojas 01",
    "qualificationLevelCode": "",
    "experienceLevelCode": "",
    "sodraPositionGroupNo": "",
    "employeeProfessionCode": "",
    "emplPostGroupId": "aa640e59-381f-ee11-a396-ce5b49aea574",
    "emplPostGroupCode": "DARB",
    "workScheduleFormulaId": "13650e59-381f-ee11-a396-ce5b49aea574",
    "wScheduleFormulaCode": "A5",
    "fte": 1,
    "vacationScheme": 20,
    "tEAType": "Apply",
    "orderNo": "",
    "managerNo": "",
    "managerId": "00000000-0000-0000-0000-000000000000",
    "workCountryCode": "",
    "workPostCode": "",
    "workCity": "",
    "workAddress": "",
    "workAddress2": "",
    "skipSPRAllocationSalaryAutoCreation": false,
    "lastModifiedDateTime": "2023-07-24T11:36:07.75Z",
    "sprDimensionSetLines": [],
    "sprAllocationSalaries": null
}

Create an allocation with a deep-inserted salary record

POST /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations?$expand=sprAllocationSalaries
Content-Type: application/json

{
    "contractId": "{contractId}",
    "startDate": "2023-07-19",
    "endDate": "0001-01-01",
    "positionId": "{positionId}",
    "emplPostGroupId": "{employeePostingGroupId}",
    "workScheduleFormulaId": "{workScheduleFormulaId}",
    "fte": 1,
    "tEAType": "Apply",
    "skipSPRAllocationSalaryAutoCreation": true,
    "sprAllocationSalaries": {
        "salaryType": "Timesheet",
        "basePayType": "Monthly",
        "basePayAmountType": "Amount",
        "basePayAmount": 1200,
        "advanceType": "Amount",
        "advanceAmount": 0
    }
}

Response — 201 Created — returns the created allocation with sprAllocationSalaries populated (instead of null).

Chain a new allocation from the current one (bound action)

POST /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations({id})/Microsoft.NAV.newUsingCurrent
Content-Type: application/json

{
    "newDate": "2023-06-15"
}

Response — 200 OK (empty body in the captured example — see the newUsingCurrent note in Remarks). Re-query by employee and date to find the new allocation's id.

Update an allocation

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

{
    "startDate": "2021-05-01",
    "endDate": "0001-01-01",
    "positionCode": "DARB01",
    "emplPostGroupCode": "DARB",
    "wScheduleFormulaCode": "A5",
    "fte": 1,
    "vacationScheme": 20,
    "tEAType": "Don't Apply"
}

Response — 200 OK — returns the updated allocation object.

Delete an allocation

DELETE /api/softera/softeraPayroll/v1.0/companies({companyId})/sprAllocations({id})
If-Match: W/"..."

Response — 204 No Content