The Companies & Plans API from 401GO — 6 operation(s) for companies & plans.
openapi: 3.2.0
info:
title: 401GO Companies & Plans API
version: 1.0.0
tags:
- name: Companies & Plans
paths:
/companies/:
get:
operationId: companies_list
description: Retrieve a list of companies that the bearer token has access to
parameters:
- 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:
- Companies & Plans
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: A Company at 401GO
properties:
object_id:
type: string
name:
type: string
maxLength: 100
status:
enum:
- SETUP_PENDING
- SETUP_COMPLETE
type: string
description: '* `SETUP_PENDING` - Setup Pending
* `SETUP_COMPLETE` - Setup Complete'
x-spec-enum-id: 2697e66770f4bfe2
readOnly: true
required:
- name
- object_id
- status
description: ''
'401':
description: 'Unauthorized: Missing or invalid authentication'
'403':
description: 'Forbidden: Insufficient permissions or scopes'
/companies/{company_id}/investment-options/:
get:
operationId: companies_investment_options_list
description: Get a list of investment options available for a given company.
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:
- Companies & Plans
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: Serializer for investment funds available in 401(k) plans.
properties:
object_id:
type: string
readOnly: true
description: Unique identifier for the investment.
name:
type: string
maxLength: 250
ticker:
type:
- string
- 'null'
maxLength: 20
description:
type: string
asset_class:
type: string
description: The asset class category of the investment.
cusip:
type:
- string
- 'null'
maxLength: 9
status:
enum:
- 1
- 2
- 3
- 4
- 50
- 100
type: integer
description: '* `1` - Active
* `2` - Inactive
* `3` - Close Only
* `4` - Halted
* `50` - Ambiguous Isin
* `100` - Unknown'
x-spec-enum-id: c4eae5f1054b2e9d
default: Unknown
required:
- asset_class
- description
- object_id
description: ''
'401':
description: 'Unauthorized: Missing or invalid authentication'
'403':
description: 'Forbidden: Insufficient permissions or scopes'
/companies/{company_id}/matches/:
get:
operationId: companies_matches_retrieve
parameters:
- in: path
name: company_id
schema:
type: string
required: true
tags:
- Companies & Plans
security:
- oauth2: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
plan_matches:
type: array
items:
type: object
properties:
contribution_rate:
type: integer
maximum: 2147483647
minimum: -2147483648
description: Match rate as a whole-number percentage (e.g., 100 for 100%, 50
for 50%).
contribution_max_percent:
type: integer
maximum: 2147483647
minimum: -2147483648
description: Maximum percentage of employee compensation this rate applies to.
Tiers are cumulative, i.e. each tier covers compensation from the previous
tier's max up to this max.
required:
- contribution_max_percent
- contribution_rate
discretionary_matches:
type: array
items:
type: object
properties:
contribution_rate:
type: integer
maximum: 2147483647
minimum: -2147483648
description: Match rate as a whole-number percentage (e.g., 100 for 100%, 50
for 50%).
contribution_max_percent:
type: integer
maximum: 2147483647
minimum: -2147483648
description: Maximum percentage of employee compensation this rate applies to.
Tiers are cumulative, i.e. each tier covers compensation from the previous
tier's max up to this max.
required:
- contribution_max_percent
- contribution_rate
discretionary_nonelective:
allOf:
- type: object
properties:
contribution_rate:
type: integer
required:
- contribution_rate
nondiscretionary_nonelective:
allOf:
- type: object
properties:
contribution_rate:
type: integer
required:
- contribution_rate
required:
- discretionary_matches
- discretionary_nonelective
- nondiscretionary_nonelective
- plan_matches
description: ''
'401':
description: 'Unauthorized: Missing or invalid authentication'
'403':
description: 'Forbidden: Insufficient permissions or scopes'
/companies/{company_id}/plan-provisions/:
get:
operationId: companies_plan_provisions_retrieve
description: "Retrieve plan provisions for a company.\n\nReturns detailed configuration settings\
\ for the 401(k) plan associated with the company.\nThis includes eligibility requirements, vesting\
\ schedules, contribution settings, and other plan provisions.\nSpecial Field Behaviors:\n \
\ - exclude_highly_compensated_and_key_employees: Only available for safe harbor plans\n -\
\ hours_of_service: Only populated when eligibility delay is 'Hours of Service'\n - allow_permissible_withdrawal:\
\ If true, allows penalty-free withdrawal within 90 days of first auto-enrollment\n - plan_cancellation_date:\
\ Uses wire_date, liquidation_date, or blackout_date in that order"
parameters:
- in: path
name: company_id
schema:
type: string
required: true
tags:
- Companies & Plans
security:
- oauth2: []
responses:
'200':
content:
application/json:
schema:
type: object
description: Serializer for retrieving plan provisions and settings.
properties:
plan_name:
type: string
maxLength: 100
plan_type:
type: string
description: Transform 'VolSubPT' to '401K', keep others as is.
readOnly: true
auto_enroll:
type: boolean
auto_enroll_percent:
type: string
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '9'
- '10'
- '11'
- '12'
- '13'
- '14'
- '15'
description: Initial automatic enrollment deferral percentage
auto_increase_by:
type:
- integer
- 'null'
description: 'Return the auto increase percentage.
Returns null if force_auto_deferral_increase is False or the plan is a QACA plan.
Otherwise, returns 1 (default value).'
readOnly: true
auto_increase_cap:
type:
- string
- 'null'
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '9'
- '10'
- '11'
- '12'
- '13'
- '14'
- '15'
description: Maximum percentage that auto-enrollment can increase to.
plan_effective_date:
type:
- string
- 'null'
format: date
plan_restatement_date:
type:
- string
- 'null'
format: date
compensation_definition:
type: string
enum:
- W-2
- Withholding
- Section 415
- Section 415 Safe Harbor
description: Defines how compensation is calculated for the plan
exclude_highly_compensated_and_key_employees:
type: boolean
description: Returns whether highly compensated and key employees are excluded.
readOnly: true
eligibility_delay:
type: string
enum:
- None
- 1 Month
- 2 Months
- 3 Months
- 4 Months
- 5 Months
- 6 Months
- 7 Months
- 8 Months
- 9 Months
- 10 Months
- 11 Months
- 1 Year
- Hours of Service
- 250 hours worked in 3 months
- 500 hours worked in 6 months
- 600 hours worked in 1 year
- 1,000 hours worked in a year
description: Specifies when participants become eligible to participate in the plan
eligibility_delay_rolling:
type: string
enum:
- Revert
- Rolling
description: If they remain ineligible after the first window, this tells what should
happen. REVERT means revert back to 1000 hours in 1 year. ROLLING means use the
next identical consecutive window. This is irrelevant for many types of plans and
can be usually left as the default
match_eligibility_delay:
type:
- string
- 'null'
enum:
- None
- 1 Month
- 2 Months
- 3 Months
- 4 Months
- 5 Months
- 6 Months
- 7 Months
- 8 Months
- 9 Months
- 10 Months
- 11 Months
- 1 Year
- Hours of Service
- 250 hours worked in 3 months
- 500 hours worked in 6 months
- 600 hours worked in 1 year
- 1,000 hours worked in a year
description: Specifies when participants become eligible for employer matching, if
different from regular eligibility
profit_share_eligibility_delay:
type:
- string
- 'null'
enum:
- None
- 1 Month
- 2 Months
- 3 Months
- 4 Months
- 5 Months
- 6 Months
- 7 Months
- 8 Months
- 9 Months
- 10 Months
- 11 Months
- 1 Year
- Hours of Service
- 250 hours worked in 3 months
- 500 hours worked in 6 months
- 600 hours worked in 1 year
- 1,000 hours worked in a year
description: Specifies when participants become eligible for profit sharing, if different
from regular eligibility
hours_of_service:
type:
- integer
- 'null'
description: 'Returns the hours of service requirement.
Returns null if eligibility_delay is not ''Hours of Service''.'
readOnly: true
vesting:
type: string
enum:
- 100% Vested
- 2-6 Year Graded
- 1-5 Year Graded
- 2 Year 50/50
- 1-4 Year Graded
- 3 Year Cliff
- 2 Year Cliff
- 1 Year Cliff
description: Specifies the vesting schedule for the plan
vesting_requires_1000_hours:
type: boolean
description: Returns whether vesting requires 1000 hours.
readOnly: true
profit_share_vesting:
type: string
enum:
- 100% Vested
- 2-6 Year Graded
- 1-5 Year Graded
- 2 Year 50/50
- 1-4 Year Graded
- 3 Year Cliff
- 2 Year Cliff
- 1 Year Cliff
description: Specifies the vesting schedule for profit sharing
profit_share_requires_last_day:
type: boolean
deferral_change_frequency:
type: string
enum:
- Each pay period
- Monthly
- Quarterly
- Semi Annual
- Hold for pay period
match_frequency:
type: string
enum:
- End of Plan Year
- Semi-annually
- Quarterly
- Each calendar month
- Each pay period
entry_date:
type: string
enum:
- Immediate
- Monthly
- Quarterly
- Semi-Annually
- Annually
match_entry_date:
type:
- string
- 'null'
enum:
- Immediate
- Monthly
- Quarterly
- Semi-Annually
- Annually
description: Only used if different from the regular entry date
profit_share_entry_date:
type:
- string
- 'null'
enum:
- Immediate
- Monthly
- Quarterly
- Semi-Annually
- Annually
description: Only used if different from the regular entry date
loans_permitted:
type: boolean
minimum_age:
type: integer
maximum: 65535
minimum: 0
match_minimum_age:
type:
- integer
- 'null'
maximum: 65535
minimum: 0
description: Only fill this in if it's different from the regular min age.
profit_share_minimum_age:
type:
- integer
- 'null'
maximum: 65535
minimum: 0
description: Only fill this in if it's different from the regular min age.
active:
type: boolean
agreed_to_edocs:
type: boolean
allow_self_direct_for_participants:
type: boolean
allow_permissible_withdrawal:
type: boolean
auto_rollover:
type: boolean
allow_roth_basis_contributions:
type: boolean
title: Allow Roth employer contributions
plan_cancellation_date:
type:
- string
- 'null'
format: date
description: 'Returns the plan cancellation date.
Returns null if there is no cancellation or if there''s an error retrieving the
date.'
readOnly: true
required:
- auto_enroll_percent
- auto_increase_by
- auto_increase_cap
- compensation_definition
- deferral_change_frequency
- eligibility_delay
- eligibility_delay_rolling
- entry_date
- exclude_highly_compensated_and_key_employees
- hours_of_service
- match_eligibility_delay
- match_entry_date
- match_frequency
- plan_cancellation_date
- plan_name
- plan_type
- profit_share_eligibility_delay
- profit_share_entry_date
- profit_share_vesting
- vesting
- vesting_requires_1000_hours
description: ''
'404':
description: 'Not Found: Plan not found'
'401':
description: 'Unauthorized: Missing or invalid authentication'
'403':
description: 'Forbidden: Insufficient permissions or scopes'
/plan-setup/:
post:
operationId: plan_setup_create
description: 'Creates a new company and 401(k) plan.
Returns an ``object_id`` identifying the new company/plan. Use it as the path parameter for
subsequent PUT/PATCH requests to update the plan.
**Fields requiring IDs from other endpoints**
Several fields accept opaque IDs that must first be retrieved from other API endpoints:
- ``acting_338``: retrieve from the *Affiliate Firms > Affiliates* or *Affiliates* endpoint.
- ``pooled_plan``: retrieve from the *Affiliate Firms > Pooled Plans* endpoint.
- ``billing_tier``: retrieve from the *Affiliate Firms > Pricing Tiers* or *Affiliates > Pricing
Tiers* endpoint.
- ``fund_lineup``: retrieve from the *Affiliate Firms > Fund Lineups* endpoint.
**Mutually exclusive fields**
- ``pooled_plan`` and ``acting_338``: provide **at most one**.
- ``employer_match_tiers`` and ``non_elective_contribution``: provide **at most one**.
**Fields that must be provided together**
- ``plan_type`` and ``plan_effective_date``: provide **both or neither**.
- ``payroll_frequency`` and ``next_payroll_date``: provide **both or neither**.
- ``grandfather_existing_employees`` requires ``plan_effective_date``.
**Fields that depend on other fields**
- ``billing_tier`` and ``fund_lineup`` each require ``acting_338`` or ``pooled_plan``.
- ``automatic_escalation_cap`` requires a non-zero ``automatic_enrollment_percentage``.
- ``safe_harbor_exclude_hce_and_key`` is only valid for safe harbor plan types.
- ``vesting_schedule`` requires ``plan_type``.
**Plan type and employer contribution rules**
Each plan type enforces specific rules for ``employer_match_tiers`` and ``non_elective_contribution``:
- **Basic Safe Harbor**: match must follow the standard formula exactly: 100% of the first 3%,
then 50% of the next 2% (up to 5%).
- **Enhanced Safe Harbor**: one match tier; total match must be a whole number between 4% and
6%.
- **Safe Harbor Non-Elective**: use ``non_elective_contribution`` (3–6%); do not provide ``employer_match_tiers``.
- **QACA Safe Harbor**: total match must be between 3.5% and 6%.
- **Traditional / Starter K / Solo K**: one match tier; total match must be a whole number between
0% and 10%.
**Plan effective date**
Must generally fall on or after the first of the following month. Exception: during December–February,
Traditional, Solo K, and Safe Harbor Non-Elective plans may use December 1st as their effective
date.
**EIN**
Only new plans are supported. If the EIN is already on the platform, the request will be rejected.
Takeover plans must be set up through other means.'
tags:
- Companies & Plans
requestBody:
content:
application/json:
schema:
type: object
description: Serializer for plan provisions and settings. Creates both a company and a plan
on POST.
properties:
company_name:
type: string
minLength: 1
description: 'Legal name of the company sponsoring the plan. Must be 2–100 characters
and begin and end with a letter or number. Allowed characters: letters, numbers, spaces,
and & '' . , ( ) - /.'
maxLength: 100
primary_contact_email:
type: string
format: email
minLength: 1
description: Email address of the company's primary contact.
maxLength: 254
primary_contact_name:
type: string
minLength: 1
description: Full name of the company's primary contact.
maxLength: 75
ein:
type: string
minLength: 1
description: 'Employer Identification Number (EIN). Accepted formats: XX-XXXXXXX or
XXXXXXXXX. Only new plans are supported. If this EIN is already on the platform the
request will be rejected.'
maxLength: 11
trustee_name:
type: string
minLength: 1
description: Full name of the plan trustee.
maxLength: 250
trustee_email:
type: string
format: email
minLength: 1
description: Email address of the plan trustee.
maxLength: 250
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
description: Physical address of the company (US only). Required on initial plan creation.
fiscal_year_end:
type: string
enum:
- Jan 31
- Feb 28
- Mar 31
- Apr 30
- May 31
- Jun 30
- Jul 31
- Aug 31
- Sep 30
- Oct 31
- Nov 30
- Dec 31
description: Last day of the company's fiscal year (e.g., 'Dec 31'). Defaults to December
31 if not provided.
primary_contact_phone:
type: string
minLength: 1
description: Phone number of the company's primary contact.
maxLength: 40
payroll_company:
type: string
enum:
- 1-2-3 Payroll
- AB Payroll
- Absolute Payroll & Insurance Services
- Accupay isolved
- Accupay Systems
- Accuserve Payroll
- ACS Accounting
- ADP Run
- ADP TotalSource
- ADP Workforce Now
- Advantage Payroll Services
- Advocate Pay LLC
- Aegis Hawaii
- Aegis Payroll
- Affiliated HR Payroll Services Evolution
- Affiliated HR Payroll Services isolved
- Ahola
- AmCheck
- American Benefits - PrismHR
- Applicant Pro isolved
- APS Payroll
- ASAP Accounting and Payroll
- Asset HR
- Asure
- Asure Software
- Auris/Heartland
- AutoPaychecks HCM isolved
- Balance Point
- Bamboo HR
- Basic Pay LLC
- BASIC Payroll LLC
- Bene-Care
- Best Payroll LLC
- Beyond HCM
- Big Fish Employer Services
- Bizchecks Payroll
- bob
- BPM
- BPS
- Brands Paycheck
- Cadence HCM LLC
- Candoor Payroll & HCM
- CBI Business Services
- CBI Payroll
- CBIZ Payroll
- Ceridian Dayforce
- CHS Payroll
- Coastal Payroll
- Coastline Payroll
- Collage
- Common Sense Payroll isolved
- Commonwealth Payroll & HR
- Compass-i, LLC
- Complete Payroll Processing
- Complete Payroll Services
- Comploy
- Computer Payroll Services Inc.
- ConnectPay
- Contrafy
- Copac Payroll
- CPM Employer Solutions
- Crescent Payroll Solutions
- Cross and Associates Payroll
- CTR Payroll
- Dial A Check
- Dominion Payroll
- Eddy HR
- Employdrive
- Encompass
- Everee
- Exact Payroll Inc
- Execupay
- Fingercheck
# --- truncated at 32 KB (281 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/401go/refs/heads/main/openapi/401go-companies-plans-api-openapi.yml