Payroll Reports API

Summary

Seven read operations expose native and compatibility summary, employee ledger, advance ledger, and compliance views.

Audience

Frontend and backend developers, QA and support engineers, architects, security reviewers, and implementation partners.

Reference Content

Authentication: bearer context is expected for business APIs; service-local enforcement Requires confirmation. Authorization: no endpoint-specific Payroll Service role policy is confirmed. Maturity: Direct and Compatibility.

Operation	Method and public route	Purpose	Authentication	Tenant context	Request type	Response type	Success	Maturity	Source path
Native Payroll summary	GET /payroll/reports/summary	List run summaries.	Bearer context expected; service-local enforcement Requires confirmation	Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation	Query parameters	PayrollSummaryReportRow[]	200	Direct	microservices/src/payroll-service/Api/PayrollOutputEndpoints.cs
Native employee ledger	GET /payroll/reports/employee-ledger/{employeeId:int}	List an employee Payroll ledger.	Bearer context expected; service-local enforcement Requires confirmation	Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation	Route and query parameters	EmployeeLedgerRow[]	200	Direct	microservices/src/payroll-service/Api/PayrollOutputEndpoints.cs
Native advance ledger	GET /payroll/reports/advance-ledger/{employeeId:int}	List one employee advance transactions.	Bearer context expected; service-local enforcement Requires confirmation	Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation	Route and query parameters	AdvanceLedgerRow[]	200	Direct	microservices/src/payroll-service/Api/PayrollOutputEndpoints.cs
Native compliance summary	GET /payroll/reports/compliance-summary	Summarize Frozen Payroll and enabled settings.	Bearer context expected; service-local enforcement Requires confirmation	Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation	Query parameters	ComplianceSummaryResponse	200	Direct	microservices/src/payroll-service/Api/PayrollOutputEndpoints.cs
Compatibility Payroll summary	GET /api/reports/payroll/summary	Return monolith-shaped period summaries.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Query parameters	Anonymous compatibility summary array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Compatibility advance ledger	GET /api/reports/payroll/advance-ledger	Return tenant-wide compatibility advance ledger.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	None	Anonymous compatibility ledger array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Compatibility compliance catalog	GET /api/reports/compliance	Return the fixed compatibility compliance-report catalog.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	None	Anonymous compatibility report array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs

Native Payroll summary

• API family / maturity: Payroll Reports API; Direct
• Authentication / authorization: Bearer context expected; service-local enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation.
• Route parameters: None.
• Query parameters: Optional tenantId, month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: PayrollSummaryReportRow[].
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: List run summaries.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: Persists report-view audit. No event produced.
• Compatibility notes: Native Payroll contract.
• Safe example: GET /payroll/reports/summary?month=7&year=2026 → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Native employee ledger

• API family / maturity: Payroll Reports API; Direct
• Authentication / authorization: Bearer context expected; service-local enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation.
• Route parameters: Required integer employee reference.
• Query parameters: Optional tenantId.
• Request body / type: None; Route and query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: EmployeeLedgerRow[].
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: List an employee Payroll ledger.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: Persists ledger-view audit. No event produced.
• Compatibility notes: Native Payroll contract.
• Safe example: GET /payroll/reports/employee-ledger/{employeeId:int} → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Native advance ledger

• API family / maturity: Payroll Reports API; Direct
• Authentication / authorization: Bearer context expected; service-local enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation.
• Route parameters: Required integer employee reference.
• Query parameters: Optional tenantId.
• Request body / type: None; Route and query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: AdvanceLedgerRow[].
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: List one employee advance transactions.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: Persists ledger-view audit. No event produced.
• Compatibility notes: Native Payroll contract.
• Safe example: GET /payroll/reports/advance-ledger/{employeeId:int} → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Native compliance summary

• API family / maturity: Payroll Reports API; Direct
• Authentication / authorization: Bearer context expected; service-local enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation.
• Route parameters: None.
• Query parameters: Optional tenantId, month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: ComplianceSummaryResponse.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Summarize Frozen Payroll and enabled settings.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: Persists report-view audit. No event produced.
• Compatibility notes: Native Payroll contract.
• Safe example: GET /payroll/reports/compliance-summary?month=7&year=2026 → 200 with run/employee counts and empty settings when absent
• Example error: No stable endpoint-specific error example is confirmed.

Compatibility Payroll summary

• API family / maturity: Payroll Reports API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: Optional month, year.
• Request body / type: None; Query parameters.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility summary array.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return monolith-shaped period summaries.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/reports/payroll/summary?month=7&year=2026 → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Compatibility advance ledger

• API family / maturity: Payroll Reports API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: None; None.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility ledger array.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return tenant-wide compatibility advance ledger.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/reports/payroll/advance-ledger → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Compatibility compliance catalog

• API family / maturity: Payroll Reports API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: None; None.
• Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
• Response body / type: Anonymous compatibility report array.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Return the fixed compatibility compliance-report catalog.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/reports/compliance → 200 report metadata array
• Example error: No stable endpoint-specific error example is confirmed.

Family-level findings

Report examples omit employee and financial data. No pagination is implemented. Native report reads add audit evidence, while compatibility report methods do not consistently add report-view audit. The compliance catalog describes compatibility report availability; it is not a filing or payment API.

Source References

• microservices/src/payroll-service/Api/PayrollOutputEndpoints.cs
• microservices/src/payroll-service/Application/PayrollOutputsService.cs
• microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
• microservices/src/payroll-service/Application/PayrollCompatService.cs
• Controllers/PayrollReportsController.cs

Related Articles

• Payroll API
• Payroll technical documentation

See Also

• Payroll business documentation
• Payroll module

Keywords

• Payroll API
• Payroll Reports API

Revision Information

• Status: Draft
• Last reviewed: 2026-07-15
• Review cycle: Quarterly