Skip to content
Vitable Docs Vitable Docs Vitable Docs
API Reference
Employers

List an employer's payroll-deduction statements

employers.list_payroll_deduction_statements(stremployer_id, EmployerListPayrollDeductionStatementsParams**kwargs) -> SyncPageNumberPage[EmployerListPayrollDeductionStatementsResponse]
GET/v1/employers/{employer_id}/payroll-deduction-statements

Returns a paginated list of the employer’s payroll-deduction statements, newest period first, each with its period, generation date, distinct employee count, total deduction, change-file link, and deduction frequency. Statements superseded by a later correction are excluded. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

ParametersExpand Collapse
employer_id: str

Unique employer identifier (empr_*)

limit: Optional[int]

Maximum number of statements per page

minimum1
maximum100
page: Optional[int]

Page number to retrieve (starts at 1)

minimum1
ReturnsExpand Collapse
class EmployerListPayrollDeductionStatementsResponse: …

One payroll-deduction statement row.

Reads a :class:PayrollDeductionStatementDTO by attribute: the statement_id character field renders the prefixed id via str(), and the date/datetime fields emit ISO-8601 strings.

csv_file_url: Optional[str]

Download link for the change CSV, or null.

deduction_frequency: Literal["weekly", "bi_weekly", "semi_monthly", "monthly"]
  • weekly - Weekly
  • bi_weekly - Bi Weekly
  • semi_monthly - Semi Monthly
  • monthly - Monthly
One of the following:
"weekly"
"bi_weekly"
"semi_monthly"
"monthly"
deduction_frequency_label: str

Human-readable deduction frequency (e.g. Monthly).

employee_count: int

Distinct employees covered by the statement’s entries.

period_end: date

Deduction period end date.

formatdate
period_start: date

Deduction period start date.

formatdate
run_date: datetime

When the statement was generated.

formatdate-time
statement_id: str

Prefixed payroll-deduction-statement identifier (pstmt_<base64-encoded-uuid>).

total_deduction_cents: int

Total payroll deduction for the period, in cents.

List an employer's payroll-deduction statements

import os
from vitable_connect import VitableConnect

client = VitableConnect(
    api_key=os.environ.get("VITABLE_CONNECT_API_KEY"),  # This is the default and can be omitted
)
page = client.employers.list_payroll_deduction_statements(
    employer_id="empr_abc123def456",
)
page = page.data[0]
print(page.statement_id)
{
  "data": [
    {
      "statement_id": "pstmt_abc123def456",
      "period_start": "2026-05-01",
      "period_end": "2026-05-31",
      "run_date": "2026-06-01T00:00:00Z",
      "employee_count": 12,
      "total_deduction_cents": 345600,
      "csv_file_url": "https://files.example/pds-1.csv",
      "deduction_frequency": "monthly",
      "deduction_frequency_label": "Monthly"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}
Returns Examples
{
  "data": [
    {
      "statement_id": "pstmt_abc123def456",
      "period_start": "2026-05-01",
      "period_end": "2026-05-31",
      "run_date": "2026-06-01T00:00:00Z",
      "employee_count": 12,
      "total_deduction_cents": 345600,
      "csv_file_url": "https://files.example/pds-1.csv",
      "deduction_frequency": "monthly",
      "deduction_frequency_label": "Monthly"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}