Skip to main content

Payroll Runs API

Summary​

Three native query operations list runs, retrieve one run, and retrieve employee outcomes. Run creation occurs through calculation; no standalone create, delete, or status-filter endpoint exists.

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 / Shadow.

OperationMethod and public routePurposeAuthenticationTenant contextRequest typeResponse typeSuccessMaturitySource path
List payroll runsGET /payroll/runsList tenant runs with optional month/year filtering.Bearer context expected; service-local enforcement Requires confirmationForwarded or explicit tenant context; exact missing-context mapping Requires confirmationQuery parametersPayrollRunResponse[]200Directmicroservices/src/payroll-service/Api/PayrollRunEndpoints.cs
Retrieve payroll runGET /payroll/runs/{id:guid}Retrieve one run summary.Bearer context expected; service-local enforcement Requires confirmationForwarded or explicit tenant context; exact missing-context mapping Requires confirmationRoute and query parametersPayrollRunResponse200Directmicroservices/src/payroll-service/Api/PayrollRunEndpoints.cs
Retrieve run detailsGET /payroll/runs/{id:guid}/detailsRetrieve employee outcomes for a run.Bearer context expected; service-local enforcement Requires confirmationForwarded or explicit tenant context; exact missing-context mapping Requires confirmationRoute and query parametersPayrollRunDetailResponse[]200Directmicroservices/src/payroll-service/Api/PayrollRunEndpoints.cs

List payroll runs​

  • API family / maturity: Payroll Runs 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: PayrollRunResponse[].
  • Success / error responses: 200; No endpoint-specific error response is mapped.
  • Business behavior: List tenant runs with optional month/year filtering.
  • State and input implications: Read-only. No input projection changes.
  • Audit and event implications: No audit side effect confirmed. No event produced.
  • Compatibility notes: Native Payroll contract.
  • Safe example: GET /payroll/runs?month=7&year=2026 → 200 []
  • Example error: No stable endpoint-specific error example is confirmed.

Retrieve payroll run​

  • API family / maturity: Payroll Runs 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 GUID runId.
  • 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: PayrollRunResponse.
  • Success / error responses: 200; 404 empty response when no matching run exists.
  • Business behavior: Retrieve one run summary.
  • State and input implications: Read-only. No input projection changes.
  • Audit and event implications: No audit side effect confirmed. No event produced.
  • Compatibility notes: Native Payroll contract.
  • Safe example: GET /payroll/runs/{id:guid} → 200 with period, status, totals metadata and detail count; missing run → 404
  • Example error: "Request could not be completed." (illustrative raw compatibility wording)

Retrieve run details​

  • API family / maturity: Payroll Runs 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 GUID runId.
  • 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: PayrollRunDetailResponse[].
  • Success / error responses: 200; No endpoint-specific error response is mapped.
  • Business behavior: Retrieve employee outcomes for a run.
  • State and input implications: Read-only. No input projection changes.
  • Audit and event implications: No audit side effect confirmed. No event produced.
  • Compatibility notes: Native Payroll contract.
  • Safe example: GET /payroll/runs/{id:guid}/details → 200 [] when no matching details exist
  • Example error: No stable endpoint-specific error example is confirmed.

Family-level findings​

PayrollRunResponse exposes run identity, tenant/period identity, status, aggregate totals, detail count, freeze metadata, and timestamps. PayrollRunDetailResponse exposes employee outcome and calculation-breakdown fields; examples intentionally omit employee and financial values. There is no pagination or status query parameter. Duplicate editable-run handling is service selection rather than CRUD completeness.

Source References​

  • microservices/src/payroll-service/Api/PayrollRunEndpoints.cs
  • microservices/src/payroll-service/Application/PayrollCalculationService.cs

See Also​

Keywords​

  • Payroll API
  • Payroll Runs API

Revision Information​

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