Date Effective Pay Rates

Use the Management V2 Employee Agreements API to create and manage employee pay configurations, including future-dated pay changes.

Base URL

/management/v2/employee-agreements

All endpoints require JWT authentication via the Authorization header.

Key concepts

An employee agreement links an employee to their pay configuration, including:

• Employment contract (award or pay template)
• Pay period
• Pay point (location)
• Effective date
• Salaried pay rule

Effective date

Use effectiveDate to determine when an employee agreement takes effect.

To schedule a future pay change, create a new agreement with a future effectiveDate. The existing agreement remains active until that date, then the new agreement applies automatically.

startAt maps to a legacy start_date field and is not used when resolving pay rates. Use effectiveDate for all date-effective changes.

Agreement history

Employee agreements are versioned through employeeAgreementHistoryId, which is updated as agreements are modified or superseded.

Data model

{
  "id": 12345,
  "employeeId": 999,
  "employmentContractId": 678,
  "payRuleId": 42,
  "payPeriodId": 1,
  "payPointId": 100,
  "effectiveDate": "2026-07-01",
  "isActive": true,
  "employeeAgreementHistoryId": 789
}

Create an employee agreement

POST /management/v2/employee-agreements

{
  "employeeId": 999,
  "employmentContractId": 678,
  "payRuleId": 42,
  "payPeriodId": 1,
  "payPointId": 100,
  "effectiveDate": "2026-07-01",
  "isActive": true
}

Required fields

Schedule a future pay change

Create a new agreement with the same employee, pay period and pay point, but a future effectiveDate.

{
  "employeeId": 999,
  "employmentContractId": 678,
  "payRuleId": 55,
  "payPeriodId": 1,
  "payPointId": 100,
  "effectiveDate": "2026-10-01",
  "isActive": true
}

The existing agreement remains in effect until 1 October 2026. The new agreement then applies automatically.

Always provide effectiveDate when creating a future-dated agreement. If it is omitted, the API assigns the current in-force date, which can cause a 400 duplicate error because that pay centre and pay period combination already exists.

Update an agreement

PUT /management/v2/employee-agreements/{id}

{
  "employmentContractId": 700,
  "payRuleId": 60,
  "payPeriodId": 2,
  "payPointId": 200
}

Use PUT to correct an existing agreement. Updating effectiveDate moves the agreement into a different date-effective bucket and reruns uniqueness validation; do not use it to schedule a new pay change.

List agreements

GET /management/v2/employee-agreements?filters=employeeId%3D999&limit=50

Supported filters include:

• employeeId=999
• isActive=true
• effectiveDate=2026-10-01
• payPointId=100
• payPeriodId=1
• employmentContractId=678
• payRuleId=42

Get a single agreement

GET /management/v2/employee-agreements/{id}

Delete an agreement

DELETE /management/v2/employee-agreements/{id}

Deleting an agreement is permanent. This endpoint performs a hard delete.

Set an employee's pay rate

To set an employee's pay rate, follow the Setting Pay Rates via the API guide.

Summary

• Use employee agreements to manage an employee's pay configuration.
• Use effectiveDate to schedule date-effective changes.
• Create a new agreement for future pay changes rather than overwriting the current agreement.
• The Employee Agreements API does not accept pay-rule overrides.