Payroll Integration API Guide

This guide provides comprehensive documentation for integrating payroll systems with the 401GO API, covering all required data fields, endpoints, and integration workflows.

1. Sending Payroll (Contributions)

Endpoint

Submit-Payroll

POST /api/companies/{company_id}/submit-payroll/

PayrollFile Fields

Field	Required	Description
`check_date`	✅ Yes	Check/Pay Date (W2 date)
`pay_period_start`	Optional	Pay period start date
`pay_period_end`	Optional	Pay period end date
`is_off_cycle`	Optional	Boolean; indicates off-cycle payroll
`payroll_lines`	✅ Yes	Array of payroll line entries

PayrollLine Fields (Per Participant)

Field	Required	Description
`participant_id`	✅ Yes	Encrypted participant identifier
`hours`	✅ Yes	Hours worked in this period
`gross_pay`	✅ Yes	Total gross pay eligible for 401(k) deductions for this period. Exclude non-eligible items such as reimbursements or bonuses that do not count toward 401(k) compensation.
`pre_tax_amount`	Conditional	Required if participant has pre-tax deferrals
`post_tax_amount`	Conditional	Required if participant has post-tax (Roth) deferrals
`company_contribution`	Optional	Employer match contribution amount
`hours_ytd`	Optional (write-only)	Year-to-date hours worked
`gross_pay_ytd`	Optional (write-only)	Year-to-date gross pay
`other_additions`	Optional	Array of additional deductions

OtherPayrollLineAdditions (Loan Payments)

Field	Required	Description
`additional_amount`	✅ Yes	Deduction amount
`other_type`	✅ Yes	Must be "Loan Principal" or "Loan Interest"

Response

Returns the created PayrollFile with read-only fields:

ach_date — Calculated ACH date
pre_tax_percent, post_tax_percent — Derived contribution percentages

2. Receiving Census Data (Participants)

Endpoints

List Participants

GET /api/companies/{company_id}/participants/ List all participants

Get Participant

GET /api/companies/{company_id}/participants/{participant_id}/ Single participant details

Create Participant

POST /api/companies/{company_id}/participants/ Create new participant

Update Participant

PATCH /api/companies/{company_id}/participants/{participant_id}/ Update participant

Required Fields for Creation

Field	Required	Description
`ssn`	✅ Yes	Social Security Number (9 digits)
`start_date`	✅ Yes	Employee hire date
`name`	✅ Yes	Full name
`email` or `phone`	✅ Yes	At least one contact method required

Optional/Conditional Fields

Field	Description
`object_id`	Required for updates
`dob`	Date of birth
`termination_date`	Termination date if applicable
`hours_worked_ytd`	Year-to-date hours worked
`compensation_ytd`	Year-to-date compensation
`years_worked_1000_hours`	Number of years with ≥1000 hours
`prior_year_total_compensation`	Previous year's compensation
`ownership_percentage`	Ownership %, if applicable
`company_officer`	Boolean; indicates officer status
`address`	Nested object (see Address Fields below)

Address Fields (If Provided)

Field	Required	Description
`address_line_1`	✅ Yes	Street address
`city`	✅ Yes	City
`state`	✅ Yes	State
`postal_code`	✅ Yes	ZIP/Postal code
`address_line_2`	Optional	Additional address line

Read-Only Fields (Received)

met_eligibility_date — Eligibility achievement date
deferrals — Current deferral elections
loans — Active loan payments
timestamp, timestamp_updated — Record creation and update timestamps

3. Receiving Plan Data

Plan Provisions

GET /api/companies/{company_id}/plan-provisions/

Plan Configuration Fields

Field	Description
`plan_name`	Plan name
`plan_type`	401K / 403B / Starter-K
`plan_effective_date`	Plan start date
`auto_enroll`	Boolean; enables auto-enrollment
`auto_enroll_percent`	Initial deferral percentage
`auto_increase_by`	Auto-increase percentage
`auto_increase_cap`	Maximum deferral percentage
`compensation_definition`	Defines compensation calculation
`eligibility_delay`	Eligibility delay rule
`eligibility_delay_rolling`	Rolling eligibility rules
`hours_of_service`	Required hours for eligibility
`minimum_age`	Minimum participant age
`match_eligibility_delay`	Match eligibility delay
`profit_share_eligibility_delay`	Profit share eligibility delay
`entry_date` / `match_entry_date` / `profit_share_entry_date`	Entry date rules
`vesting`	Vesting schedule type
`vesting_requires_1000_hours`	Boolean
`profit_share_vesting`	Profit share vesting schedule
`profit_share_requires_last_day`	Boolean
`deferral_change_frequency`	How often deferrals can change
`match_frequency`	Employer match frequency
`loans_permitted`	Boolean; allows participant loans
`exclude_highly_compensated_and_key_employees`	Safe harbor exclusion
`agreed_to_edocs`	Boolean
`allow_self_direct_for_participants`	Boolean
`allow_permissible_withdrawal`	Boolean
`auto_rollover`	Boolean
`allow_roth_basis_contributions`	Boolean
`active`	Boolean; plan active status
`plan_cancellation_date`	If plan is terminated

Employer Match Details

GET /api/companies/{company_id}/matches/

Field	Description
`plan_matches`	Array of match tiers (rate and max %)
`discretionary_matches`	Array of discretionary matches
`discretionary_nonelective`	Discretionary non-elective contributions
`nondiscretionary_nonelective`	Non-discretionary non-elective contributions

4. Receiving Deduction Updates

Deferrals

GET /participants/{participant_id}/deferrals/

Field	Description
`amount`	Deferral amount or percentage
`is_percent`	Boolean; true if percentage
`timestamp`	Last update timestamp
`active_traditional`	Active traditional deferrals
`active_roth`	Active Roth deferrals
`change_frequency`	Change frequency allowed
`is_eligible`	Boolean; if participant is eligible
`hit_max`	Boolean; if annual max reached

Loans

GET /participants/{participant_id}/loan-requests/

Returns active loans needing deductions:

todays_payment — Amount due per payroll

Payroll History

GET /participants/{participant_id}/payroll-lines/

Returns historical payroll lines for previous deductions.

5. Participant Updates via Payroll

When submitting payroll, participant records can be automatically updated:

Field	Description
`hours_ytd`	Updates `hours_worked_ytd` in participant record
`gross_pay_ytd`	Updates `compensation_ytd` in participant record

Note: These are write-only fields within the PayrollLine.

6. Integration Workflow Summary

Sync Census - Import all participants using the participants endpoints
Retrieve Plan Provisions - Get plan configuration and match details
Get Deferrals - Fetch current deferral elections for each participant

Data Flow Diagrams

Flow 1 — Initial Setup & Data Sync

┌──────────────┐                                    ┌──────────────┐
│   PARTNER    │                                    │    401GO     │
│   SYSTEM     │                                    │              │
└──────┬───────┘                                    └──────┬───────┘
       │                                                   │
       │ 1. Retrieve companies and plan info               │
       │────────────────────────────────────────────────>  │
       │                                                   │
       │ 2. Cache plan provisions, match formulas,         │
       │    and eligibility rules                          │
       │ <──────────────────────────────────────────────   │
       │                                                   │
       │ 3. Retrieve and sync participant census data      │
       │────────────────────────────────────────────────>  │
       │                                                   │
       │ 4. Maintain updated employee records locally      │
       │ <──────────────────────────────────────────────   │
       │                                                   │

Flow 2 — Per-Participant Deduction Retrieval

┌──────────────┐                                    ┌──────────────┐
│   PARTNER    │                                    │    401GO     │
│   SYSTEM     │                                    │              │
└──────┬───────┘                                    └──────┬───────┘
       │                                                   │
       │ 1. Retrieve each participant's deferral & loan    │
       │    information                                    │
       │────────────────────────────────────────────────>  │
       │                                                   │
       │ 2. Calculate deductions and verify eligibility    │
       │ <──────────────────────────────────────────────   │
       │                                                   │

Flow 3 — Submitting Payroll Data

┌──────────────┐                                    ┌──────────────┐
│   PARTNER    │                                    │    401GO     │
│   SYSTEM     │                                    │              │
└──────┬───────┘                                    └──────┬───────┘
       │                                                   │
       │ 1. Submit payroll file with employee deductions   │
       │────────────────────────────────────────────────>  │
       │                                                   │
       │ 2. 401GO validates, processes, and calculates ACH │
       │    contribution amounts                           │
       │ <──────────────────────────────────────────────   │
       │                                                   │
       │ 3. Partner stores payroll reference for tracking  │
       │                                                   │