The Participants API from 401GO — 4 operation(s) for participants.
openapi: 3.2.0
info:
title: 401GO Participants API
version: 1.0.0
tags:
- name: Participants
paths:
/companies/{company_id}/participants/:
get:
operationId: companies_participants_list
description: Retrieve a list of participants for the given company_id. This will also include the
current deductions for participants (deferrals and loan payments).
parameters:
- in: path
name: company_id
schema:
type: string
required: true
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- Participants
security:
- oauth2: []
responses:
'200':
content:
application/json:
schema:
type: object
required:
- count
- results
properties:
count:
type: integer
example: 123
next:
type:
- string
- 'null'
format: uri
example: http://api.example.org/accounts/?page=4
previous:
type:
- string
- 'null'
format: uri
example: http://api.example.org/accounts/?page=2
results:
type: array
items:
type: object
description: 'Represents a participant in a companies 401k account. ''met_eligibility_date''
will be returned as non-null and in the past once a participant
is eligible to contribute. In addition, for ineligible participants, the deferrals
will always have a 0 amount.
When creating a participant, either phone or email are required (preferably both).
When updating a participant, object_id is required.
If a ''termination_date'' has previously been set, pushing a ''start_date'' after
it will rehire this participant.'
properties:
object_id:
type:
- string
- 'null'
name:
type: string
maxLength: 100
email:
type: string
format: email
default: ''
phone:
type: string
default: ''
start_date:
type: string
format: date
description: The latest date this participant was hired or rehired. Pushing
a start_date that is after a previously set termination_date will rehire this
participant.
termination_date:
type:
- string
- 'null'
format: date
met_eligibility_date:
type:
- string
- 'null'
format: date
readOnly: true
met_match_eligibility_date:
type:
- string
- 'null'
format: date
readOnly: true
met_profit_share_eligibility_date:
type:
- string
- 'null'
format: date
readOnly: true
ssn:
type: string
title: Social Security Number
maxLength: 9
dob:
type:
- string
- 'null'
format: date
title: Birthday
hours_worked_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
compensation_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
years_worked_1000_hours:
type:
- integer
- 'null'
maximum: 65535
minimum: 0
prior_year_total_compensation:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
deferrals:
allOf:
- 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
readOnly: true
loans:
type: array
items:
type: object
description: Represents a due loan payment
properties:
todays_payment:
type: string
readOnly: true
required:
- todays_payment
readOnly: true
ownership_percentage:
type: string
company_officer:
type: boolean
address:
allOf:
- type: object
description: A participant's Address
properties:
address_line_1:
type: string
maxLength: 100
address_line_2:
type: string
maxLength: 100
city:
type: string
maxLength: 80
state:
type: string
maxLength: 80
postal_code:
type: string
maxLength: 20
country:
type: string
default: US
maxLength: 80
required:
- address_line_1
- city
- postal_code
- state
timestamp:
type: string
format: date-time
readOnly: true
timestamp_updated:
type: string
format: date-time
readOnly: true
required:
- deferrals
- loans
- met_eligibility_date
- met_match_eligibility_date
- met_profit_share_eligibility_date
- ssn
- start_date
- timestamp
- timestamp_updated
description: ''
'401':
description: 'Unauthorized: Missing or invalid authentication'
'403':
description: 'Forbidden: Insufficient permissions or scopes'
post:
operationId: companies_participants_create
description: 'Create a new participant or multiple new participants for the given company_id. You
cannot add deductions or set ''met_eligibility_date''.
Note the required fields on the schema. If you attempt to add an employee that already exists
(by ssn), it will attempt to update that employee.'
parameters:
- in: path
name: company_id
schema:
type: string
required: true
tags:
- Participants
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
description: 'Represents a participant in a companies 401k account. ''met_eligibility_date''
will be returned as non-null and in the past once a participant
is eligible to contribute. In addition, for ineligible participants, the deferrals will
always have a 0 amount.
When creating a participant, either phone or email are required (preferably both). When
updating a participant, object_id is required.
If a ''termination_date'' has previously been set, pushing a ''start_date'' after it
will rehire this participant.'
properties:
object_id:
type:
- string
- 'null'
name:
type: string
maxLength: 100
email:
type: string
format: email
minLength: 1
default: ''
phone:
type: string
minLength: 1
default: ''
start_date:
type: string
format: date
description: The latest date this participant was hired or rehired. Pushing a start_date
that is after a previously set termination_date will rehire this participant.
termination_date:
type:
- string
- 'null'
format: date
ssn:
type: string
minLength: 1
title: Social Security Number
maxLength: 9
dob:
type:
- string
- 'null'
format: date
title: Birthday
hours_worked_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
compensation_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
years_worked_1000_hours:
type:
- integer
- 'null'
maximum: 65535
minimum: 0
prior_year_total_compensation:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
ownership_percentage:
type: string
company_officer:
type: boolean
address:
allOf:
- type: object
description: A participant's Address
properties:
address_line_1:
type: string
minLength: 1
maxLength: 100
address_line_2:
type: string
maxLength: 100
city:
type: string
minLength: 1
maxLength: 80
state:
type: string
minLength: 1
maxLength: 80
postal_code:
type: string
minLength: 1
maxLength: 20
country:
type: string
minLength: 1
default: US
maxLength: 80
required:
- address_line_1
- city
- postal_code
- state
required:
- ssn
- start_date
- type: array
items:
type: object
description: 'Represents a participant in a companies 401k account. ''met_eligibility_date''
will be returned as non-null and in the past once a participant
is eligible to contribute. In addition, for ineligible participants, the deferrals
will always have a 0 amount.
When creating a participant, either phone or email are required (preferably both).
When updating a participant, object_id is required.
If a ''termination_date'' has previously been set, pushing a ''start_date'' after
it will rehire this participant.'
properties:
object_id:
type:
- string
- 'null'
name:
type: string
maxLength: 100
email:
type: string
format: email
minLength: 1
default: ''
phone:
type: string
minLength: 1
default: ''
start_date:
type: string
format: date
description: The latest date this participant was hired or rehired. Pushing a start_date
that is after a previously set termination_date will rehire this participant.
termination_date:
type:
- string
- 'null'
format: date
ssn:
type: string
minLength: 1
title: Social Security Number
maxLength: 9
dob:
type:
- string
- 'null'
format: date
title: Birthday
hours_worked_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
compensation_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
years_worked_1000_hours:
type:
- integer
- 'null'
maximum: 65535
minimum: 0
prior_year_total_compensation:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
ownership_percentage:
type: string
company_officer:
type: boolean
address:
allOf:
- type: object
description: A participant's Address
properties:
address_line_1:
type: string
minLength: 1
maxLength: 100
address_line_2:
type: string
maxLength: 100
city:
type: string
minLength: 1
maxLength: 80
state:
type: string
minLength: 1
maxLength: 80
postal_code:
type: string
minLength: 1
maxLength: 20
country:
type: string
minLength: 1
default: US
maxLength: 80
required:
- address_line_1
- city
- postal_code
- state
required:
- ssn
- start_date
application/x-www-form-urlencoded:
schema:
oneOf:
- type: object
description: 'Represents a participant in a companies 401k account. ''met_eligibility_date''
will be returned as non-null and in the past once a participant
is eligible to contribute. In addition, for ineligible participants, the deferrals will
always have a 0 amount.
When creating a participant, either phone or email are required (preferably both). When
updating a participant, object_id is required.
If a ''termination_date'' has previously been set, pushing a ''start_date'' after it
will rehire this participant.'
properties:
object_id:
type:
- string
- 'null'
name:
type: string
maxLength: 100
email:
type: string
format: email
minLength: 1
default: ''
phone:
type: string
minLength: 1
default: ''
start_date:
type: string
format: date
description: The latest date this participant was hired or rehired. Pushing a start_date
that is after a previously set termination_date will rehire this participant.
termination_date:
type:
- string
- 'null'
format: date
ssn:
type: string
minLength: 1
title: Social Security Number
maxLength: 9
dob:
type:
- string
- 'null'
format: date
title: Birthday
hours_worked_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
compensation_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
years_worked_1000_hours:
type:
- integer
- 'null'
maximum: 65535
minimum: 0
prior_year_total_compensation:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
ownership_percentage:
type: string
company_officer:
type: boolean
address:
allOf:
- type: object
description: A participant's Address
properties:
address_line_1:
type: string
minLength: 1
maxLength: 100
address_line_2:
type: string
maxLength: 100
city:
type: string
minLength: 1
maxLength: 80
state:
type: string
minLength: 1
maxLength: 80
postal_code:
type: string
minLength: 1
maxLength: 20
country:
type: string
minLength: 1
default: US
maxLength: 80
required:
- address_line_1
- city
- postal_code
- state
required:
- ssn
- start_date
- type: array
items:
type: object
description: 'Represents a participant in a companies 401k account. ''met_eligibility_date''
will be returned as non-null and in the past once a participant
is eligible to contribute. In addition, for ineligible participants, the deferrals
will always have a 0 amount.
When creating a participant, either phone or email are required (preferably both).
When updating a participant, object_id is required.
If a ''termination_date'' has previously been set, pushing a ''start_date'' after
it will rehire this participant.'
properties:
object_id:
type:
- string
- 'null'
name:
type: string
maxLength: 100
email:
type: string
format: email
minLength: 1
default: ''
phone:
type: string
minLength: 1
default: ''
start_date:
type: string
format: date
description: The latest date this participant was hired or rehired. Pushing a start_date
that is after a previously set termination_date will rehire this participant.
termination_date:
type:
- string
- 'null'
format: date
ssn:
type: string
minLength: 1
title: Social Security Number
maxLength: 9
dob:
type:
- string
- 'null'
format: date
title: Birthday
hours_worked_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
compensation_ytd:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
years_worked_1000_hours:
type:
- integer
- 'null'
maximum: 65535
minimum: 0
prior_year_total_compensation:
type: string
format: decimal
pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
ownership_percentage:
type: string
company_officer:
type: boolean
address:
allOf:
- type: object
description: A participant's Address
properties:
address_line_1:
type: string
minLength: 1
maxLength: 100
address_line_2:
type: string
maxLength: 100
city:
type: string
minLength: 1
maxLength: 80
state:
type: string
minLength: 1
maxLength: 80
postal_code:
type: string
minLength: 1
maxLength: 20
country:
type: string
minLength: 1
default: US
maxLength: 80
required:
- address_line_1
- city
- postal_code
- state
required:
- ssn
- start_date
multipart/form-data:
schema:
oneOf:
- type: object
description: 'Represents a participant in a companies 401k account. ''met_eligibility_date''
will be returned as non-null and in the past once a participant
is eligible to contribute. In addition, for ineligible participants, the deferrals will
# --- truncated at 32 KB (130 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/401go/refs/heads/main/openapi/401go-participants-api-openapi.yml