Employee Balances

This page provides a comprehensive reference for all parameters, endpoints, and behaviors of the Employee Balances API. Use this guide to understand request/response structures, validation rules, and integration best practices.

Purpose:
The Employee Balances API provides read-only access to employee balance information, such as vacation, overtime, and other payroll-related balances. It enables employees to retrieve their own balances and allows authorized integrations to retrieve balances for a specific employee resource.

Base URL:
/v1/employee-balances

Additional User-scoped Endpoint /v1/me/employee-balances

Authentication:
All APIs require a Client ID and Client Secret.
Refer to the global authentication documentation for details.

System Parameters:
No Employee Balances-specific system parameters are required to use this API.

Supported Methods

Swagger / Schema

Version v1

Method Details

• GET Method (Single)
• GET Method (Multiple)
• GET Method (Additional)

GET /v1/me/employee-balances/ABL

{ 
  "companyId": "EN", 
  "personId": "8871", 
  "balanceId": "ABL", 
  "description": "Annual Balance", 
  "balanceCategory": "AB01", 
  "balanceCategoryDescription": "Annual balance group", 
  "registrationUnit": "U01", 
  "currentValue": 12, 
  "remark": "Manual", 
  "limitValue": 0, 
  "isLimitWrittenDown": false 
}

GET /v1/me/employee-balances

GET /v1/me/employee-balances?shownChoice=ShownInAll

[   
  { 
    "companyId": "EN", 
    "personId": "88701", 
    "balanceId": "ABC", 
    "description": "Absence balance", 
    "balanceCategory": "AB01", 
    "balanceCategoryDescription": "Annual balance group", 
    "registrationUnit": "Days", 
    "currentValue": -7, 
    "limitValue": 0, 
    "isLimitWrittenDown": false 
  }, 

  { 
    "companyId": "EN", 
    "personId": "88702", 
    "balanceId": "ABL", 
    "description": "Annual Balance", 
    "balanceCategory": "AB01", 
    "balanceCategoryDescription": "Annual balance group", 
    "registrationUnit": "Days", 
    "currentValue": 12, 
    "limitValue": 0, 
    "isLimitWrittenDown": false 
  } 
]

GET /v1/employee-balances/8870

[   
  {
    "dateFrom": "1900-01-01T00:00:00.000", 
    "dateTo": "2099-12-31T00:00:00.000", 
    "startValue": 0, 
    "companyId": "EN", 
    "personId": "8870", 
    "balanceId": "ABL", 
    "attribute2": "C0", 
    "attribute2Description": "Resource position", 
    "attribute2Value": "0073", 
    "attribute2ValueDescription": "Engineer", 
    "description": "Annual Balance", 
    "balanceCategory": "AB01", 
    "balanceCategoryDescription": "Annual balance group", 
    "registrationUnit": "Days", 
    "currentValue": -7, 
    "remark": "Manual", 
    "limitValue": 0, 
    "isLimitWrittenDown": false 
  }, 
  {
    "dateFrom": "1900-01-01T00:00:00.000", 
    "dateTo": "2099-12-31T00:00:00.000", 
    "startValue": 0, 
    "companyId": "EN", 
    "personId": "8870", 
    "balanceId": "ABC", 
    "attribute2": "C0", 
    "attribute2Description": "Resource position", 
    "attribute2Value": "0073", 
    "attribute2ValueDescription": "Engineer", 
    "description": "Absence balance", 
    "balanceCategory": "AB01", 
    "balanceCategoryDescription": "Annual balance group", 
    "registrationUnit": "Days", 
    "currentValue": -7, 
    "remark": "Manual", 
    "limitValue": 0, 
    "isLimitWrittenDown": false 
  } 
]

Best Practices

• Use /me endpoints for the current user: Use the /me endpoints when retrieving balances for the logged-in user. This simplifies integration by eliminating the need to manage employee resource IDs.
• Use resource-based endpoints for administrative scenarios: Use the /employee-balances/{resourceId} endpoint when retrieving balances for employees other than the logged-in user.
• Apply filters where possible: Use the balanceId and shownChoice parameters to reduce response payload size and improve performance.
• Follow API throttling and rate-limiting policies: Although this endpoint does not define specific record count or rate limits, integrations must comply with tenant-wide Public API throttling and rate-limiting policies.
• Validate requests with Swagger UI: Use Swagger UI to test requests and verify response schemas before deploying to production.
• Handle error responses gracefully: Implement appropriate handling for 400, 403, and 404 responses to ensure a resilient integration.
• Validate employee-to-resource mappings: Ensure that logged-in users are associated with a valid employee/resource record before attempting to retrieve balances.
• Monitor endpoint versioning and deprecation notices: Review deprecation announcements regularly and plan migrations before endpoint versions are retired.
• Handle empty result sets: Ensure integrations can process responses where no balances are available for the specified employee.

Related Endpoints

Action APIs

Query APIs (Read-Only)