Skip to main content

Extracting Payroll Deductions

This guide details how payroll providers and plan administrators extract employee payroll deductions and employer subsidies from Aptia One for scheduled pay runs.

Workflow Overview​

1. Fetch Deduction Calendar ──► GET /v1/tenants/{tenantId}/payroll-schedules
                                      │
2. Query Participant Deductions ──► GET /v1/participants/{id}/payroll-deductions?effectiveDate=2026-05-01
                                      │
3. Feed Payroll General Ledger ──► Ingest into Partner Payroll Software

1. Retrieving Tenant Payroll Schedules​

To determine pay period dates, frequency (e.g. BiWeekly, SemiMonthly), and deduction cutoff deadlines for a client, query GET /v1/tenants/{tenantId}/payroll-schedules:

curl -X GET "https://api.development.aptiaone.com/v1/tenants/tenant-001/payroll-schedules?year=2026" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response (200 OK)​

{
  "tenantId": "tenant-001",
  "schedules": [
    {
      "scheduleId": "f6789abc-def0-1234-5678-9abcdef01234",
      "payrollSystemId": "01234567-89ab-cdef-0123-456789abcdef",
      "scheduleName": "Bi-Weekly Standard Salary Schedule",
      "financialProcess": "PAYROLL",
      "periods": [
        {
          "start": "2026-05-01",
          "end": "2026-05-14",
          "checkDate": "2026-05-22",
          "cutoffDate": "2026-05-18",
          "importDate": "2026-05-24",
          "payrollYear": 2026,
          "financialProcess": "PAYROLL"
        }
      ]
    }
  ]
}

2. Querying Calculated Participant Deductions​

To extract the exact pre-tax and post-tax deductions calculated for a participant, call GET /v1/participants/{participantId}/payroll-deductions:

curl -X GET "https://api.development.aptiaone.com/v1/participants/22222222-2222-2222-2222-222222222222/payroll-deductions?effectiveDate=2026-05-01" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response (200 OK)​

{
  "participantId": "22222222-2222-2222-2222-222222222222",
  "tenantId": "tenant-001",
  "deductions": [
    {
      "deductionId": "e56789ab-cdef-0123-4567-89abcdef0123",
      "deductionCode": "MED_PRE",
      "payPeriodStart": "2026-05-01",
      "payPeriodEnd": "2026-05-14",
      "checkDate": "2026-05-22",
      "cutoffDate": "2026-05-18",
      "calculatedAmount": 145.50,
      "allocatedAmount": 145.50,
      "expectedAmount": 145.50,
      "arrearsAmount": 0.00,
      "retroactivityAmount": 0.00,
      "payrollScheduleId": "f6789abc-def0-1234-5678-9abcdef01234",
      "coverages": [
        {
          "planId": "a1234567-89ab-cdef-0123-456789abcdef",
          "coverageId": "d456789a-bcde-f012-3456-789abcdef012"
        }
      ]
    },
    {
      "deductionId": "e56789ab-cdef-0123-4567-89abcdef0124",
      "deductionCode": "DNT_PRE",
      "payPeriodStart": "2026-05-01",
      "payPeriodEnd": "2026-05-14",
      "checkDate": "2026-05-22",
      "cutoffDate": "2026-05-18",
      "calculatedAmount": 22.00,
      "allocatedAmount": 22.00,
      "expectedAmount": 22.00,
      "arrearsAmount": 0.00,
      "retroactivityAmount": 0.00,
      "payrollScheduleId": "f6789abc-def0-1234-5678-9abcdef01234",
      "coverages": [
        {
          "planId": "b1234567-89ab-cdef-0123-456789abcdef",
          "coverageId": null
        }
      ]
    }
  ]
}

3. General Ledger & Payroll Reconciliation​

  • Tax Treatment: PreTax deductions (Section 125 cafeteria plans) must reduce taxable gross wages before federal and state withholding calculation. PostTax voluntary benefits are deducted after taxes.
  • Subsidies: employerContributionAmount reflects plan sponsor premium liability and can be matched directly against carrier billing remittances.