# 401GO Documentation > Documentation for 401GO ## Guides - [Getting Started with 401GO's API](https://developer.401go.com/docs/getting-started.md): Welcome to the 401GO API documentation! This guide will help you integrate with our API, covering authentication, setup, and key steps for launching a successful integration. - [Authentication](https://developer.401go.com/docs/authentication.md): The 401GO API uses the **OAuth 2.0** protocol for authentication and authorization. Follow these steps to securely access our API: - [Client Credentials Flow](https://developer.401go.com/docs/client-credentials-flow.md): While the preferred authentication method for the 401GO API is the **Authorization Code Flow**, we allow certain partners to authenticate using the **Client Credentials Flow**. This flow is suitable for machine-to-machine authentication where user interaction is not required. - [Single Sign-On (SSO) with OpenID Connect (OIDC)](https://developer.401go.com/docs/single-sign-on-sso-with-openid-connect-oidc.md): This API supports Single Sign-On (SSO) using the OpenID Connect (OIDC) Authorization Code Flow. Authenticaiton uses the OAuth 2.0 Authorization Code Grant flow with the `openid` scope. - [Versioning](https://developer.401go.com/docs/versioning.md): The 401GO API employs a header-based versioning scheme. Versioning is done per-endpoint with a provided date header. - [Handling Errors](https://developer.401go.com/docs/api-errors.md) - [Payroll Integration API Guide](https://developer.401go.com/docs/payroll-integration.md): Complete guide for integrating payroll systems with the 401GO API, including required data fields, endpoints, workflow processes, and data flow diagrams. - [API Endpoint and Method Access](https://developer.401go.com/docs/api-endpoint-and-method-access.md) ## API Reference - [/affiliate-firms/](https://developer.401go.com/reference/affiliate_firms_list.md): Returns all affiliate firms the authenticated user has permission to access. - [/affiliate-firms/{affiliate_firm_id}/affiliates/](https://developer.401go.com/reference/affiliate_firms_affiliates_list.md): Returns the list of affiliates belonging to the given affiliate firm. - [/affiliate-firms/{affiliate_firm_id}/fund-lineups/](https://developer.401go.com/reference/affiliate_firms_fund_lineups_list.md): Returns fund lineups for the given affiliate firm. Only available for 338 firms. - [/affiliate-firms/{affiliate_firm_id}/pooled-plans/](https://developer.401go.com/reference/affiliate_firms_pooled_plans_list.md): Returns pooled plans provided by the given affiliate firm. - [/affiliate-firms/{affiliate_firm_id}/pricing-tiers/](https://developer.401go.com/reference/affiliate_firms_pricing_tiers_list.md): Returns pricing tiers for the given affiliate firm. - [/affiliates/{affiliate_id}/pricing-tiers/](https://developer.401go.com/reference/affiliates_pricing_tiers_list.md): Returns pricing tiers for the given affiliate. - [/companies/{company_id}/company-affiliates/](https://developer.401go.com/reference/companies_company_affiliates_retrieve.md): Returns broker-dealer, advisor, and advisor firm data for the given company. Notes: - Some or all returned fields may be null. - Advisor and firm CRD numbers may not always be available. - If the company is working with a specific advisor from a firm, that advisor will be included in the response. - If the company works with a firm but not a specific advisor, the advisor field will be null. - [/companies/](https://developer.401go.com/reference/companies_list.md): Retrieve a list of companies that the bearer token has access to - [/companies/{company_id}/investment-options/](https://developer.401go.com/reference/companies_investment_options_list.md): Get a list of investment options available for a given company. - [/companies/{company_id}/matches/](https://developer.401go.com/reference/companies_matches_retrieve.md) - [/companies/{company_id}/plan-provisions/](https://developer.401go.com/reference/companies_plan_provisions_retrieve.md): Retrieve plan provisions for a company. Returns detailed configuration settings for the 401(k) plan associated with the company. This includes eligibility requirements, vesting schedules, contribution settings, and other plan provisions. Special Field Behaviors: - exclude_highly_compensated_and_key_employees: Only available for safe harbor plans - hours_of_service: Only populated when eligibility delay is 'Hours of Service' - allow_permissible_withdrawal: If true, allows penalty-free withdrawal within 90 days of first auto-enrollment - plan_cancellation_date: Uses wire_date, liquidation_date, or blackout_date in that order - [/plan-setup/](https://developer.401go.com/reference/plan_setup_create.md): 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. - [/plan-setup/{company_id}/](https://developer.401go.com/reference/plan_setup_update.md): Updates an existing 401(k) plan. The ``{id}`` path parameter is the ``object_id`` returned from the POST response. Partial updates (PATCH) will not work. Endpoint currently only supports full replacement (PUT). Updates are blocked if the plan has been modified through the web portal after initial API setup, or if the plan is or was active. - [/companies/{company_id}/participants/](https://developer.401go.com/reference/companies_participants_list.md): Retrieve a list of participants for the given company_id. This will also include the current deductions for participants (deferrals and loan payments). - [/companies/{company_id}/participants/](https://developer.401go.com/reference/companies_participants_create.md): 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. - [/companies/{company_id}/participants/{participant_id}/](https://developer.401go.com/reference/companies_participants_retrieve.md): Retrieve a participant by id for the given company_id. This will also include the current deductions for a participant (deferrals and loan payments). - [/companies/{company_id}/participants/{participant_id}/](https://developer.401go.com/reference/companies_participants_update.md): Update an existing participant by id for the given company_id. You cannot add deductions or update met_eligibility_date. If you try to change an email, it will create an additional login for the user with the new email so it doesn't lock out their previous login - [/companies/{company_id}/participants/{participant_id}/](https://developer.401go.com/reference/companies_participants_partial_update.md): Update an existing participant by id for the given company_id. You cannot add deductions or update met_eligibility_date. If you try to change an email, it will create an additional login for the user with the new email so it doesn't lock out their previous login - [/participants/{participant_id}/events/](https://developer.401go.com/reference/participants_events_retrieve.md): Gets a list of the different event types that exist for a participant. To check whether a participant's dashboard is accessible, check for the 'completed setup' event. - [/participants/{participant_id}/events/](https://developer.401go.com/reference/participants_events_create.md): Adds a list of the different event types for a participant. It will not duplicate events. - [/participants/{participant_id}/participant-setup/](https://developer.401go.com/reference/participants_participant_setup_retrieve.md): Gets plan data for the associated participant, and if they've set their deferral elections. Choices for 'plan_type' are 'Volume Submitter Prototype Format' (401k plans), '403B', and 'Starter-K' - [/companies/{company_id}/submit-payroll/](https://developer.401go.com/reference/companies_submit_payroll_create.md): Submit payroll for a company. - [/participants/{participant_id}/deferrals/](https://developer.401go.com/reference/participants_deferrals_retrieve.md): Get deferrals for a participant. - [/participants/{participant_id}/deferrals/](https://developer.401go.com/reference/participants_deferrals_create.md): 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. - [/participants/{participant_id}/matches/](https://developer.401go.com/reference/participants_matches_retrieve.md) - [/participants/{participant_id}/payroll-lines/](https://developer.401go.com/reference/participants_payroll_lines_list.md): Get the payroll lines for a participant. - [/participants/{participant_id}/totals/](https://developer.401go.com/reference/participants_totals_retrieve.md): Returns year-to-date contribution totals, account balances, income, loans, and applicable annual contribution limits. Includes YTD totals for: - Pre-tax contributions - Post-tax contributions - Company contributions - Compensation (YTD and prior year) Also includes: - Total account balance - Cash balance - Active loan balances - Payroll count for the year Contribution limits: - Pre-tax and post-tax contributions share a single combined contribution limit. This means contributions to EITHER pre-tax OR post-tax reduce the remaining limit for BOTH. Example: If the contribution limit is $23,000 and a participant contributes $10,000 pre-tax, they can contribute at most $13,000 more total across pre-tax and post-tax combined. - Catch-up contributions have special eligibility rules. A participant may be eligible for Roth (post-tax) catch-up without being eligible for traditional (pre-tax) catch-up. - The `year_contribution_limit` is the absolute maximum for all contributions combined: pre-tax + post-tax + all catch-up contributions. - Each contribution type may not exceed its own individual limit. - [/investments/{investment_id}/](https://developer.401go.com/reference/investments_retrieve.md): API endpoints for retrieving investment fund information. - [/participants/{participant_id}/cancel-participant-rebalance/](https://developer.401go.com/reference/participants_cancel_participant_rebalance_create.md) - [/participants/{participant_id}/investment-history/](https://developer.401go.com/reference/participants_investment_history_list.md): Get a list of investment transactions for the given participant id. You can optionally paginate by including 'page={page_num}&page_size={page_size}' in the query string. Possible statuses: pending, confirmed, failed, dividend. - [/participants/{participant_id}/investment-options/](https://developer.401go.com/reference/participants_investment_options_list.md): Get a list of investment options available to the given participant. You can optionally paginate by including 'page={page_num}&page_size={page_size}' in the query string. - [/participants/{participant_id}/investment-performance/](https://developer.401go.com/reference/participants_investment_performance_list.md): Get a list of portfolios - one for each day between two dates. - [/participants/{participant_id}/portfolio/](https://developer.401go.com/reference/participants_portfolio_list.md): Gets a list of portfolio investments for the given participant. ### Investment states - `ACTIVE`: Investment is part of the portfolio. - `PENDING_SALE`: Investment has been removed from the portfolio and is being fully liquidated. - [/participants/{participant_id}/portfolio/](https://developer.401go.com/reference/participants_portfolio_create.md): Updates a participant's target portfolio allocations. Expects: - `investments`: list of investment ids - `weights`: list of target percent weights (aligned by index with `investments`) ### 0% allocations Setting an investment target allocation to `0%` does **not** remove it from the portfolio. If `auto_rebalance` is disabled, no trades will occur until a manual rebalance is triggered. ### Removing an investment Any allocation you specify in a POST request replaces any prior allocation. Thus, to remove an investment from the portfolio, simply post an allocation without that investment. Once an investment is removed from the portfolio, the system will sell all shares of that investment **regardless of whether `auto_rebalance` is enabled**. Removed investments enter `PENDING_SALE` until liquidation is complete. - [/participants/{participant_id}/portfolio-settings/](https://developer.401go.com/reference/participants_portfolio_settings_retrieve.md): Get data points related to rebalancing, trading windows, and if a participant can self direct. can_cancel_rebalance represents if the current time is in a trading window. The next_trading_window returns the start of the next trading window and should be used with caution, preferably with a buffer of about 30 minutes for if the trade can be completed in this time. - [/participants/{participant_id}/portfolio-settings/](https://developer.401go.com/reference/participants_portfolio_settings_create.md): Updates a participant's option to auto rebalance, rebalance percent, and if they have opted in to self direct - [/participants/{participant_id}/start-participant-rebalance/](https://developer.401go.com/reference/participants_start_participant_rebalance_create.md) - [/participants/{participant_id}/advisor-models/](https://developer.401go.com/reference/participants_advisor_models_retrieve.md) - [/participants/{participant_id}/advisor-models/](https://developer.401go.com/reference/participants_advisor_models_create.md) - [/participants/{participant_id}/retirement-planning-defaults/](https://developer.401go.com/reference/participants_retirement_planning_defaults_retrieve.md): Get the defaults used for the estimation. Note that the defaults returned may not be valid for getting an estimate, for example if `age > retirement_age`. - [/participants/{participant_id}/retirement-planning-estimate/](https://developer.401go.com/reference/participants_retirement_planning_estimate_list.md): Estimate a participant's projected balance and target savings for retirement. Will use the defaults as defined from the retirement-planning-defaults unless an override is given. Can only be used if the participant has not yet reached retirement, or the supplied `age` is less than `retirement_age`. - [/participants/{participant_id}/beneficiaries/](https://developer.401go.com/reference/participants_beneficiaries_list.md): Get a list of a participant's beneficiaries. - [/participants/{participant_id}/beneficiaries/](https://developer.401go.com/reference/participants_beneficiaries_create.md): Create a single or multiple beneficiaries for a participant. If a list is provided, either all or none will be created. - [/participants/{participant_id}/beneficiaries/](https://developer.401go.com/reference/participants_beneficiaries_partial_update.md): Partially update a list of beneficiaries. Each entry must include the `object_id`. The provided list must be a subset of the participant's beneficiaries. Validates every entry first, then either applies all or none of them. - [/participants/{participant_id}/beneficiaries/{beneficiary_id}/](https://developer.401go.com/reference/participants_beneficiaries_retrieve.md): Retrieve a specific beneficiary. - [/participants/{participant_id}/beneficiaries/{beneficiary_id}/](https://developer.401go.com/reference/participants_beneficiaries_update.md): Fully update a specific beneficiary. - [/participants/{participant_id}/beneficiaries/{beneficiary_id}/](https://developer.401go.com/reference/participants_beneficiaries_partial_update_2.md): Partially update a single beneficiary. - [/participants/{participant_id}/beneficiaries/{beneficiary_id}/](https://developer.401go.com/reference/participants_beneficiaries_destroy.md): Delete a beneficiary. - [/participants/{participant_id}/disbursements/](https://developer.401go.com/reference/participants_disbursements_list.md): Get a list of participant's disbursements. - [/participants/{participant_id}/disbursements/](https://developer.401go.com/reference/participants_disbursements_create.md): Create a new disbursement request. Field Usage Patterns: 1. Single Disbursement (pre-tax only or post-tax only): - Use regular fields (payment_method, bank_name, etc.) for payment details - Use pretax_memo for pre-tax disbursements - Use posttax_memo for post-tax disbursements - Use payment_address for pre-tax disbursements - Use posttax_payment_address for post-tax disbursements 2. Split Disbursement (both pre-tax and post-tax): - Use regular fields (payment_method, bank_name, etc.) for pre-tax portion - Use posttax_* fields for post-tax portion if different from pre-tax - Both pretax_memo and posttax_memo are required - Both payment_address and posttax_payment_address can be specified if different - [/participants/{participant_id}/disbursements-info/](https://developer.401go.com/reference/participants_disbursements_info_retrieve.md): Get information about available disbursement options before creating one. Query parameters can be used to get accurate available amounts for different disbursement types: - is_hardship: Calculate amounts for hardship disbursements - is_emergency: Calculate amounts for emergency expense disbursements - is_move_rollover: Calculate amounts for move rollover disbursements All parameters default to false if not specified. - [/participants/{participant_id}/disbursements/{disbursement_id}/](https://developer.401go.com/reference/participants_disbursements_retrieve.md): ViewSet for handling participant disbursements in a single request. - [/participants/{participant_id}/disbursements/{disbursement_id}/](https://developer.401go.com/reference/participants_disbursements_update.md): Update a specific disbursement request. - [/participants/{participant_id}/disbursements/{disbursement_id}/](https://developer.401go.com/reference/participants_disbursements_destroy.md): Delete a disbursement request. - [/participants/{participant_id}/loan-requests/](https://developer.401go.com/reference/participants_loan_requests_list.md): Get a list of a participant's loan requests. - [/participants/{participant_id}/loan-requests/](https://developer.401go.com/reference/participants_loan_requests_create.md): Create a loan request. - [/participants/{participant_id}/loan-requests-info/](https://developer.401go.com/reference/participants_loan_requests_info_retrieve.md): Get information that is useful before beginning a loan request. - [/participants/{participant_id}/loan-requests-signature/{loan_request_id}/](https://developer.401go.com/reference/participants_loan_requests_signature_update.md): Submit a signature for this loan request. - [/participants/{participant_id}/loan-requests/{loan_request_id}/](https://developer.401go.com/reference/participants_loan_requests_retrieve.md): Retrieve a specific loan request. - [/participants/{participant_id}/loan-requests/{loan_request_id}/](https://developer.401go.com/reference/participants_loan_requests_update.md): Fully update a specific loan request. - [/participants/{participant_id}/loan-requests/{loan_request_id}/](https://developer.401go.com/reference/participants_loan_requests_destroy.md): Delete a loan request. - [/participants/{participant_id}/money-movement-history/](https://developer.401go.com/reference/participants_money_movement_history_list.md): Get a list of money movement transactions for the given participant id. The account type will be Pre-tax for employee pre-tax movements, Post-tax for employee post-tax movements, Vested Contribution for any vested employer contributions, Non-vested Contribution for any non-vested employer contributions. The tax_type field is only really useful to distinguish pre-tax or post-tax employer contributions when it has a value. - [/participants/{participant_id}/rollovers/](https://developer.401go.com/reference/participants_rollovers_list.md): Get a list of participant's rollovers. - [/participants/{participant_id}/rollovers/](https://developer.401go.com/reference/participants_rollovers_create.md): Create a new rollover in one single request. - [/participants/{participant_id}/rollovers/{rollover_id}/](https://developer.401go.com/reference/participants_rollovers_retrieve.md): Retrieve a specific rollover request. - [/participants/{participant_id}/rollovers/{rollover_id}/](https://developer.401go.com/reference/participants_rollovers_update.md): Update a specific rollover request. - [/participants/{participant_id}/rollovers/{rollover_id}/](https://developer.401go.com/reference/participants_rollovers_destroy.md): Delete a rollover request. - [/participants/{participant_id}/notifications/](https://developer.401go.com/reference/participants_notifications_list.md): Get a list of notifications for a participant. - [/participants/{participant_id}/notifications/{notification_id}/](https://developer.401go.com/reference/participants_notifications_partial_update.md) - [/participants/{participant_id}/notifications/attachment/{attachment_id}/](https://developer.401go.com/reference/participants_notifications_attachment_retrieve.md): Returns a signed url for the given attachment that will last for 30 minutes. - [/participants/{participant_id}/participant-documents/](https://developer.401go.com/reference/list_participant_documents.md): Returns a list of participant related documents. - [/participants/{participant_id}/participant-documents/{document_name}/](https://developer.401go.com/reference/get_signed_participant_document_url.md): Returns a signed url for the given named document that will last for 30 minutes.