/plan-setup/

post

https://sandbox.401go.com/api/plan-setup/

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Serializer for plan provisions and settings. Creates both a company and a plan on POST.

company_name

string

required

length between 1 and 100

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 & ' . , ( ) - /.

primary_contact_email

string

required

length between 1 and 254

Email address of the company's primary contact.

primary_contact_name

string

required

length between 1 and 75

Full name of the company's primary contact.

ein

string

length between 1 and 11

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.

trustee_name

string

length between 1 and 250

Full name of the plan trustee.

trustee_email

string

length between 1 and 250

Email address of the plan trustee.

address

object

A participant's Address

fiscal_year_end

string

enum

Last day of the company's fiscal year (e.g., 'Dec 31'). Defaults to December 31 if not provided.

primary_contact_phone

string

length between 1 and 40

Phone number of the company's primary contact.

payroll_company

string

enum

Name of the company's payroll provider.

naics_code

string

length between 1 and 6

6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.

control_group

boolean

Set to true if this company is part of a controlled group or affiliated service group (ASG).

entity_type

string

enum

Legal entity type of the company (e.g., Corporation, LLC, Partnership).

entity_state

string

enum

State or territory where the company is incorporated or primarily operates.

plan_name

string

length between 1 and 100

Name of the 401(k) plan. Follows the same character rules as company_name.

plan_type

string

enum

Type of 401(k) plan. Must always be provided together with plan_effective_date (both or neither). Each plan type enforces specific employer contribution rules. See endpoint description for details.

Yes - safe harbor match - Yes - safe harbor match
Yes - nonelective contribution - Yes - nonelective contribution
Yes - QACA safe harbor match - Yes - QACA safe harbor match
Yes - enhanced safe harbor match - Yes - enhanced safe harbor match
No - No
Starter-K - Starter-K
Solo-K - Solo-K

Allowed:

automatic_enrollment_percentage

string

enum

Default deferral percentage for automatic enrollment. Use 0 to opt out of automatic enrollment. A value of 0 is only permitted for businesses founded within the past 3 years or with fewer than 11 employees.

automatic_escalation_cap

string

enum

Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage.

Allowed:

plan_effective_date

date

Date the plan becomes effective. Must always be provided together with plan_type (both or neither). Must 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.

compensation_definition

string

enum

How employee compensation is defined for contribution calculations.

Allowed:

safe_harbor_exclude_hce_and_key

boolean

Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types.

service_requirement

string

enum

Minimum service period an employee must complete before becoming eligible to defer.

match_service_requirement

string

enum

Minimum service period an employee must complete before becoming eligible for employer match contributions.

profit_sharing_service_requirement

string

enum

Minimum service period an employee must complete before becoming eligible for profit sharing contributions.

vesting_schedule

string

enum

Employer match vesting schedule. Requires plan_type to be set. For QACA Safe Harbor plans, must be one of: 100% immediate, 2-year 50/50, or 2-year cliff.

profit_sharing_vesting_schedule

string

enum

Vesting schedule for profit sharing contributions.

profit_sharing_requires_employment_on_last_day

boolean

Whether employees must be employed on the last day of the plan year to receive profit sharing contributions.

deferral_change_frequency

string

enum

How frequently employees are permitted to change their deferral percentage.

Allowed:

deferral_entry_frequency

string

enum

How frequently new employees become eligible to begin deferring into the plan.

Allowed:

employer_match_entry_frequency

string

enum

How frequently new employees become eligible to receive employer match contributions.

Allowed:

profit_sharing_entry_frequency

string

enum

How frequently new employees become eligible to receive profit sharing contributions.

Allowed:

allow_participant_loans

boolean

Whether participants are permitted to take loans from their plan accounts.

deferral_minimum_age

integer

Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer.

employer_match_minimum_age

integer

Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match.

profit_sharing_minimum_age

integer

Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing.

employer_match_tiers

array of objects

Employer match formula expressed as one or more tiers. Cannot be provided together with non_elective_contribution. Each tier specifies contribution_rate (integer match percentage) and contribution_max_percent (maximum percentage of compensation this rate applies to). Required format varies by plan type. See endpoint description for per-plan-type rules.

employer_match_tiers

non_elective_contribution

integer

Employer non-elective (guaranteed) contribution as a percentage of each eligible employee's compensation. Cannot be provided together with employer_match_tiers. For Safe Harbor Non-Elective plans, must be between 3 and 6 (inclusive).

payroll_frequency

string

enum

How often the company runs payroll. If providing this field you must also provide next_payroll_date.

Allowed:

next_payroll_date

date

Date of the company's next scheduled payroll. Must be in the future and within 365 days. Must be on or after plan_effective_date if provided. If providing this field you must also provide payroll_frequency.

number_of_employees

integer

Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions.

grandfather_existing_employees

boolean

Whether employees already employed on the plan effective date should be grandfathered in as immediately eligible. Requires plan_effective_date to also be provided.

employee_notification_date

date

Date on which employees will be notified of the plan. Must be in the future and at least 2 days before plan_effective_date.

business_start_date

date

Date the company was founded. Used to determine whether the company qualifies for SECURE 2.0 automatic enrollment exemptions (businesses founded within the past 3 years).

acting_338

string | null

ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms/<affiliate_firm_id>/affiliates/ endpoint. An affiliate firm ID may also be provided to assign that affiliate firm as the 3(38). Mutually exclusive with pooled_plan. Provide one or the other.

billing_tier

string | null

ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms/<affiliate_firm_id>/pricing-tiers/ or affiliates/<affiliate_id>/pricing-tiers/ endpoint. The tier must belong to the acting_338 or the pooled plan's 3(38). Requires acting_338 or pooled_plan to also be provided.

fund_lineup

string | null

Opaque ID of the fund lineup to assign to this plan. Retrieve this ID from the Affiliate Firms > Fund Lineups endpoint. The lineup must belong to the same firm as acting_338 or the pooled plan. Requires acting_338 or pooled_plan to also be provided.

pooled_plan

string | null

Opaque ID of the pooled employer plan (PEP) to join as an adopting employer. Retrieve this ID from the Affiliate Firms > Pooled Plans endpoint. You must have permission to access the pooled plan's provider. Mutually exclusive with acting_338. Provide one or the other.

Headers

content-type

string

enum

Defaults to application/json

Generated from available request content types

Allowed:

Responses

400

Bad Request: Invalid plan setup data.

401

Unauthorized: Missing or invalid authentication

403

Forbidden: Insufficient permissions or scopes

200