The Contributions & Payroll API from 401GO — 5 operation(s) for contributions & payroll.
openapi: 3.2.0
info:
title: 401GO Contributions & Payroll API
version: 1.0.0
tags:
- name: Contributions & Payroll
paths:
/companies/{company_id}/submit-payroll/:
post:
operationId: companies_submit_payroll_create
description: Submit payroll for a company.
parameters:
- in: header
name: Idempotent-Key
schema:
type: string
description: Supply a key to safely retry requests without the server duplicating the action.
Will be remembered for 24 hours.
- in: path
name: company_id
schema:
type: string
required: true
tags:
- Contributions & Payroll
requestBody:
content:
application/json:
schema:
type: object
description: 'A Payroll File is a single payroll for a company with many pay lines, one
for each participant.
There are a couple dates that can be provided for a payroll file, but check_date is the
only required one.
is_off_cycle can be true if this is not a regular payroll. For example, it could be a
one-off correction.'
properties:
pay_period_start:
type:
- string
- 'null'
format: date
pay_period_end:
type:
- string
- 'null'
format: date
check_date:
type: string
format: date
title: Check/Pay Date (W2 date)
is_off_cycle:
type: boolean
payroll_lines:
type: array
items:
type: object
description: 'A payroll line represents payroll for one participant and has the associated
id of that participant.
It can also optionally include hours_ytd and gross_pay_ytd which will help in reporting,
eligibility, etc. when provided.'
properties:
participant_id:
type: string
hours:
type: string
format: decimal
pattern: ^-?\d{0,4}(?:\.\d{0,2})?$
gross_pay:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
pre_tax_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
post_tax_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
company_contribution:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
other_additions:
type: array
items:
type: object
description: 'Additional payroll deductions not covered by employee contributions
to 401k or company matches.
Currently, this can only be set to Loan types.'
properties:
additional_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
other_type:
enum:
- Loan Principal
- Loan Interest
type: string
description: '* `Loan Principal` - Loan Principal
* `Loan Interest` - Loan Interest'
x-spec-enum-id: a05082d953d3615e
required:
- additional_amount
- other_type
hours_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
writeOnly: true
gross_pay_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
writeOnly: true
required:
- gross_pay
- hours
- participant_id
required:
- check_date
- payroll_lines
application/x-www-form-urlencoded:
schema:
type: object
description: 'A Payroll File is a single payroll for a company with many pay lines, one
for each participant.
There are a couple dates that can be provided for a payroll file, but check_date is the
only required one.
is_off_cycle can be true if this is not a regular payroll. For example, it could be a
one-off correction.'
properties:
pay_period_start:
type:
- string
- 'null'
format: date
pay_period_end:
type:
- string
- 'null'
format: date
check_date:
type: string
format: date
title: Check/Pay Date (W2 date)
is_off_cycle:
type: boolean
payroll_lines:
type: array
items:
type: object
description: 'A payroll line represents payroll for one participant and has the associated
id of that participant.
It can also optionally include hours_ytd and gross_pay_ytd which will help in reporting,
eligibility, etc. when provided.'
properties:
participant_id:
type: string
hours:
type: string
format: decimal
pattern: ^-?\d{0,4}(?:\.\d{0,2})?$
gross_pay:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
pre_tax_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
post_tax_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
company_contribution:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
other_additions:
type: array
items:
type: object
description: 'Additional payroll deductions not covered by employee contributions
to 401k or company matches.
Currently, this can only be set to Loan types.'
properties:
additional_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
other_type:
enum:
- Loan Principal
- Loan Interest
type: string
description: '* `Loan Principal` - Loan Principal
* `Loan Interest` - Loan Interest'
x-spec-enum-id: a05082d953d3615e
required:
- additional_amount
- other_type
hours_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
writeOnly: true
gross_pay_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
writeOnly: true
required:
- gross_pay
- hours
- participant_id
required:
- check_date
- payroll_lines
multipart/form-data:
schema:
type: object
description: 'A Payroll File is a single payroll for a company with many pay lines, one
for each participant.
There are a couple dates that can be provided for a payroll file, but check_date is the
only required one.
is_off_cycle can be true if this is not a regular payroll. For example, it could be a
one-off correction.'
properties:
pay_period_start:
type:
- string
- 'null'
format: date
pay_period_end:
type:
- string
- 'null'
format: date
check_date:
type: string
format: date
title: Check/Pay Date (W2 date)
is_off_cycle:
type: boolean
payroll_lines:
type: array
items:
type: object
description: 'A payroll line represents payroll for one participant and has the associated
id of that participant.
It can also optionally include hours_ytd and gross_pay_ytd which will help in reporting,
eligibility, etc. when provided.'
properties:
participant_id:
type: string
hours:
type: string
format: decimal
pattern: ^-?\d{0,4}(?:\.\d{0,2})?$
gross_pay:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
pre_tax_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
post_tax_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
company_contribution:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
other_additions:
type: array
items:
type: object
description: 'Additional payroll deductions not covered by employee contributions
to 401k or company matches.
Currently, this can only be set to Loan types.'
properties:
additional_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
other_type:
enum:
- Loan Principal
- Loan Interest
type: string
description: '* `Loan Principal` - Loan Principal
* `Loan Interest` - Loan Interest'
x-spec-enum-id: a05082d953d3615e
required:
- additional_amount
- other_type
hours_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
writeOnly: true
gross_pay_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
writeOnly: true
required:
- gross_pay
- hours
- participant_id
required:
- check_date
- payroll_lines
required: true
security:
- oauth2: []
responses:
'200':
content:
application/json:
schema:
type: object
description: 'A Payroll File is a single payroll for a company with many pay lines, one
for each participant.
There are a couple dates that can be provided for a payroll file, but check_date is
the only required one.
is_off_cycle can be true if this is not a regular payroll. For example, it could be
a one-off correction.'
properties:
pay_period_start:
type:
- string
- 'null'
format: date
pay_period_end:
type:
- string
- 'null'
format: date
check_date:
type: string
format: date
title: Check/Pay Date (W2 date)
ach_date:
type:
- string
- 'null'
format: date
readOnly: true
is_off_cycle:
type: boolean
payroll_lines:
type: array
items:
type: object
description: 'A payroll line represents payroll for one participant and has the
associated id of that participant.
It can also optionally include hours_ytd and gross_pay_ytd which will help in
reporting, eligibility, etc. when provided.'
properties:
participant_id:
type: string
hours:
type: string
format: decimal
pattern: ^-?\d{0,4}(?:\.\d{0,2})?$
gross_pay:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
pre_tax_percent:
type: string
format: decimal
pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
readOnly: true
description: Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05
pre_tax_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
post_tax_percent:
type: string
format: decimal
pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
readOnly: true
description: Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05
post_tax_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
company_contribution:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
other_additions:
type: array
items:
type: object
description: 'Additional payroll deductions not covered by employee contributions
to 401k or company matches.
Currently, this can only be set to Loan types.'
properties:
additional_amount:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
other_type:
enum:
- Loan Principal
- Loan Interest
type: string
description: '* `Loan Principal` - Loan Principal
* `Loan Interest` - Loan Interest'
x-spec-enum-id: a05082d953d3615e
required:
- additional_amount
- other_type
check_date:
type: string
format: date
readOnly: true
required:
- check_date
- gross_pay
- hours
- participant_id
- post_tax_percent
- pre_tax_percent
required:
- ach_date
- check_date
- payroll_lines
description: ''
'400':
description: 'Bad Request: Invalid payroll data'
'401':
description: 'Unauthorized: Missing or invalid authentication'
'403':
description: 'Forbidden: Insufficient permissions or scopes'
/participants/{participant_id}/deferrals/:
get:
operationId: participants_deferrals_retrieve
description: Get deferrals for a participant.
parameters:
- in: path
name: participant_id
schema:
type: string
required: true
tags:
- Contributions & Payroll
security:
- oauth2: []
- knoxApiToken: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
traditional:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
roth:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
change_frequency:
enum:
- Each pay period
- Monthly
- Quarterly
- Semi Annual
- Hold for pay period
type:
- string
- 'null'
readOnly: true
description: Frequency that this participant's updated deferrals will become active.
active_traditional:
allOf:
- type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be
updated.
is_percent:
type: boolean
required:
- amount
- timestamp
readOnly: true
description: Currently active traditional deferrals. May be different from `traditional`
field.
active_roth:
allOf:
- type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be
updated.
is_percent:
type: boolean
required:
- amount
- timestamp
readOnly: true
description: Currently active roth deferrals. May be different from `roth` field.
is_eligible:
type: boolean
readOnly: true
description: If this participant is eligible.
hit_max:
type: boolean
readOnly: true
description: If this participant has hit their max for the year.
required:
- active_roth
- active_traditional
- change_frequency
- hit_max
- is_eligible
description: ''
'401':
description: 'Unauthorized: Missing or invalid authentication'
'403':
description: 'Forbidden: Insufficient permissions or scopes'
post:
operationId: participants_deferrals_create
description: 'Update deferrals for a participant. Submitted deferrals may not immediately become
active due to eligibility,
maxing out for the year, or plan deferral change frequency rules.'
parameters:
- in: path
name: participant_id
schema:
type: string
required: true
tags:
- Contributions & Payroll
requestBody:
content:
application/json:
schema:
type: object
properties:
traditional:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
roth:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
application/x-www-form-urlencoded:
schema:
type: object
properties:
traditional:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
roth:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
multipart/form-data:
schema:
type: object
properties:
traditional:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
roth:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
security:
- oauth2: []
- knoxApiToken: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
traditional:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
roth:
type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be updated.
is_percent:
type: boolean
required:
- amount
- timestamp
change_frequency:
enum:
- Each pay period
- Monthly
- Quarterly
- Semi Annual
- Hold for pay period
type:
- string
- 'null'
readOnly: true
description: Frequency that this participant's updated deferrals will become active.
active_traditional:
allOf:
- type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
type: string
format: date-time
description: Timestamp for conflict resolution. If older than the last deferral
update in our system, an error will be returned and deferrals will not be
updated.
is_percent:
type: boolean
required:
- amount
- timestamp
readOnly: true
description: Currently active traditional deferrals. May be different from `traditional`
field.
active_roth:
allOf:
- type: object
properties:
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
timestamp:
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/401go/refs/heads/main/openapi/401go-contributions-payroll-api-openapi.yml