{ "openapi": "3.0.3", "info": { "title": "401GO APIs", "version": "1.0.0" }, "paths": { "/affiliate-firms/": { "get": { "operationId": "affiliate_firms_list", "description": "Returns all affiliate firms the authenticated user has permission to access.", "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": [ "Affiliates & Firms" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string", "readOnly": true }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 }, "contact_name": { "type": "string", "maxLength": 75 }, "contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "is_338_firm": { "type": "boolean", "readOnly": true } }, "required": [ "address", "crd", "is_338_firm", "name", "object_id" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/affiliate-firms/{affiliate_firm_id}/affiliates/": { "get": { "operationId": "affiliate_firms_affiliates_list", "description": "Returns the list of affiliates belonging to the given affiliate firm.", "parameters": [ { "in": "path", "name": "affiliate_firm_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": [ "Affiliates & Firms" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string" }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "address", "crd", "name", "object_id" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/affiliate-firms/{affiliate_firm_id}/fund-lineups/": { "get": { "operationId": "affiliate_firms_fund_lineups_list", "description": "Returns fund lineups for the given affiliate firm. Only available for 338 firms.", "parameters": [ { "in": "path", "name": "affiliate_firm_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": [ "Affiliates & Firms" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "description": "This short 250 char description will be shown on the 'Select Fund Lineup' page of the company questions section of plan setup. If there are fees for this lineup, they should be listed here.", "maxLength": 250 }, "custodian": { "type": "string", "enum": [ "Matrix", "Drive Wealth", "Apex", "Matrix And Drive Wealth", "Matrix And Apex", "Drive Wealth And Apex", "Matrix And Drive Wealth And Apex" ] }, "investments": { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] }, "readOnly": true } }, "required": [ "custodian", "investments", "object_id" ] } } } } } }, "description": "" }, "400": { "description": "Bad Request: Only 338 firms have fund lineups." }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/affiliate-firms/{affiliate_firm_id}/pooled-plans/": { "get": { "operationId": "affiliate_firms_pooled_plans_list", "description": "Returns pooled plans provided by the given affiliate firm.", "parameters": [ { "in": "path", "name": "affiliate_firm_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": [ "Affiliates & Firms" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 }, "effective_date": { "type": "string", "format": "date", "nullable": true }, "terminated_date": { "type": "string", "format": "date", "nullable": true }, "status": { "enum": [ "DRAFT", "ACTIVE", "INACTIVE" ], "type": "string", "description": "* `DRAFT` - DRAFT\n* `ACTIVE` - ACTIVE\n* `INACTIVE` - INACTIVE", "x-spec-enum-id": "8b036d93c4c21fd8" }, "matrix_alliance_code": { "type": "string", "maxLength": 16 } }, "required": [ "name", "object_id" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/affiliate-firms/{affiliate_firm_id}/pricing-tiers/": { "get": { "operationId": "affiliate_firms_pricing_tiers_list", "description": "Returns pricing tiers for the given affiliate firm.", "parameters": [ { "in": "path", "name": "affiliate_firm_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": [ "Affiliates & Firms" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "tier_name": { "type": "string", "maxLength": 100 }, "aum_tiers_banded": { "type": "boolean" }, "aum_tiers": { "type": "array", "items": { "type": "object", "properties": { "aum_limit": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "aum_fee": { "type": "string", "format": "decimal", "description": "Fee as a decimal (e.g. 0.0100 = 1% = 100 bps). To convert from bps, divide by 10,000." } } }, "readOnly": true }, "per_head_tiers": { "type": "array", "items": { "type": "object", "properties": { "participant_limit": { "type": "integer" }, "dollar_per_head": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "participant_limit" ] }, "readOnly": true }, "other_fees": { "type": "array", "items": { "type": "object", "properties": { "fee_frequency": { "type": "string", "enum": [ "One-Time", "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly", "Quarterly", "Semi-Annually", "Yearly" ] }, "fee_description": { "type": "string" }, "fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "fee_description", "fee_frequency" ] }, "readOnly": true } }, "required": [ "aum_tiers", "aum_tiers_banded", "object_id", "other_fees", "per_head_tiers" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/affiliates/{affiliate_id}/pricing-tiers/": { "get": { "operationId": "affiliates_pricing_tiers_list", "description": "Returns pricing tiers for the given affiliate.", "parameters": [ { "in": "path", "name": "affiliate_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": [ "Affiliates & Firms" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "tier_name": { "type": "string", "maxLength": 100 }, "aum_tiers_banded": { "type": "boolean" }, "aum_tiers": { "type": "array", "items": { "type": "object", "properties": { "aum_limit": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "aum_fee": { "type": "string", "format": "decimal", "description": "Fee as a decimal (e.g. 0.0100 = 1% = 100 bps). To convert from bps, divide by 10,000." } } }, "readOnly": true }, "per_head_tiers": { "type": "array", "items": { "type": "object", "properties": { "participant_limit": { "type": "integer" }, "dollar_per_head": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "participant_limit" ] }, "readOnly": true }, "other_fees": { "type": "array", "items": { "type": "object", "properties": { "fee_frequency": { "type": "string", "enum": [ "One-Time", "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly", "Quarterly", "Semi-Annually", "Yearly" ] }, "fee_description": { "type": "string" }, "fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "fee_description", "fee_frequency" ] }, "readOnly": true } }, "required": [ "aum_tiers", "aum_tiers_banded", "object_id", "other_fees", "per_head_tiers" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/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", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "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\n* `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}/company-affiliates/": { "get": { "operationId": "companies_company_affiliates_retrieve", "description": "Returns broker-dealer, advisor, and advisor firm data for the given company.\n\nNotes:\n- Some or all returned fields may be null.\n- Advisor and firm CRD numbers may not always be available.\n- If the company is working with a specific advisor from a firm, that advisor will be included in the response.\n- If the company works with a firm but not a specific advisor, the advisor field will be null.", "parameters": [ { "in": "path", "name": "company_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Affiliates & Firms" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "broker_dealer": { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 75 }, "address": { "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" ] }, "contact_name": { "type": "string", "maxLength": 75 } }, "required": [ "address" ] } ], "nullable": true }, "advisor": { "allOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string" }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "address", "crd", "name", "object_id" ] } ], "nullable": true }, "advisor_firm": { "allOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string", "readOnly": true }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 }, "contact_name": { "type": "string", "maxLength": 75 }, "contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "is_338_firm": { "type": "boolean", "readOnly": true } }, "required": [ "address", "crd", "is_338_firm", "name", "object_id" ] } ], "nullable": true } }, "required": [ "advisor", "advisor_firm", "broker_dealer" ] } } }, "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", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `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" ] } ], "nullable": true }, "nondiscretionary_nonelective": { "allOf": [ { "type": "object", "properties": { "contribution_rate": { "type": "integer" } }, "required": [ "contribution_rate" ] } ], "nullable": true } }, "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}/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", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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'.\nNote 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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "required": [ "ssn", "start_date" ] } } ] } } } }, "security": [ { "oauth2": [] } ], "responses": { "200": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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" ] }, { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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": "" }, "400": { "description": "Bad Request: Invalid participant data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/companies/{company_id}/participants/{participant_id}/": { "get": { "operationId": "companies_participants_retrieve", "description": "Retrieve a participant by id for the given company_id. This will also include the current deductions for a participant (deferrals and loan payments).", "parameters": [ { "in": "path", "name": "company_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Participants" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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" } } }, "put": { "operationId": "companies_participants_update", "description": "Update an existing participant by id for the given company_id. You cannot add deductions or update met_eligibility_date.\nIf 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", "parameters": [ { "in": "path", "name": "company_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Participants" ], "requestBody": { "content": { "application/json": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "required": [ "ssn", "start_date" ] } }, "application/x-www-form-urlencoded": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "required": [ "ssn", "start_date" ] } }, "multipart/form-data": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "required": [ "ssn", "start_date" ] } } }, "required": true }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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": "" }, "400": { "description": "Bad Request: Invalid participant data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "patch": { "operationId": "companies_participants_partial_update", "description": "Update an existing participant by id for the given company_id. You cannot add deductions or update met_eligibility_date.\nIf 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", "parameters": [ { "in": "path", "name": "company_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Participants" ], "requestBody": { "content": { "application/json": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } } } }, "application/x-www-form-urlencoded": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } } } }, "multipart/form-data": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } } } } } }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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": "" }, "400": { "description": "Bad Request: Invalid participant data" }, "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", "description": "Return the auto increase percentage.\nReturns null if force_auto_deferral_increase is False or the plan is a QACA plan.\nOtherwise, returns 1 (default value).", "readOnly": true, "nullable": true }, "auto_increase_cap": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" ], "nullable": true, "description": "Maximum percentage that auto-enrollment can increase to." }, "plan_effective_date": { "type": "string", "format": "date", "nullable": true }, "plan_restatement_date": { "type": "string", "format": "date", "nullable": true }, "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", "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" ], "nullable": true, "description": "Specifies when participants become eligible for employer matching, if different from regular eligibility" }, "profit_share_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" ], "nullable": true, "description": "Specifies when participants become eligible for profit sharing, if different from regular eligibility" }, "hours_of_service": { "type": "integer", "description": "Returns the hours of service requirement.\nReturns null if eligibility_delay is not 'Hours of Service'.", "readOnly": true, "nullable": 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", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "nullable": true, "description": "Only used if different from the regular entry date" }, "profit_share_entry_date": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true, "description": "Only fill this in if it's different from the regular min age." }, "profit_share_minimum_age": { "type": "integer", "maximum": 65535, "minimum": 0, "nullable": true, "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", "format": "date", "description": "Returns the plan cancellation date.\nReturns null if there is no cancellation or if there's an error retrieving the date.", "readOnly": true, "nullable": 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" } } } }, "/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.\n\nThere are a couple dates that can be provided for a payroll file, but check_date is the only required one.\nis_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", "format": "date", "nullable": true }, "pay_period_end": { "type": "string", "format": "date", "nullable": true }, "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.\n\nIt 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.\n\nCurrently, 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\n* `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.\n\nThere are a couple dates that can be provided for a payroll file, but check_date is the only required one.\nis_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", "format": "date", "nullable": true }, "pay_period_end": { "type": "string", "format": "date", "nullable": true }, "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.\n\nIt 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.\n\nCurrently, 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\n* `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.\n\nThere are a couple dates that can be provided for a payroll file, but check_date is the only required one.\nis_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", "format": "date", "nullable": true }, "pay_period_end": { "type": "string", "format": "date", "nullable": true }, "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.\n\nIt 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.\n\nCurrently, 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\n* `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.\n\nThere are a couple dates that can be provided for a payroll file, but check_date is the only required one.\nis_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", "format": "date", "nullable": true }, "pay_period_end": { "type": "string", "format": "date", "nullable": true }, "check_date": { "type": "string", "format": "date", "title": "Check/Pay Date (W2 date)" }, "ach_date": { "type": "string", "format": "date", "readOnly": true, "nullable": 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.\n\nIt 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.\n\nCurrently, 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\n* `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" } } } }, "/investments/{investment_id}/": { "get": { "operationId": "investments_retrieve", "description": "API endpoints for retrieving investment fund information.", "parameters": [ { "in": "path", "name": "investment_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } } }, "description": "" } } } }, "/participants/{participant_id}/advisor-models/": { "get": { "operationId": "participants_advisor_models_retrieve", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Retirement Planning" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "description": "No response body" } } }, "post": { "operationId": "participants_advisor_models_create", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Retirement Planning" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "selected_model": { "type": "string", "minLength": 1 } }, "required": [ "selected_model" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "selected_model": { "type": "string", "minLength": 1 } }, "required": [ "selected_model" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "selected_model": { "type": "string", "minLength": 1 } }, "required": [ "selected_model" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "investment": { "allOf": [ { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } ], "readOnly": true }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "value": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "status": { "enum": [ "PENDING_SALE", "ACTIVE" ], "type": "string", "description": "* `PENDING_SALE` - Pending Sale\n* `ACTIVE` - Active", "x-spec-enum-id": "a442a24a44038e9a", "readOnly": true } }, "required": [ "investment", "percent", "shares", "status", "value" ] } } } } } }, "description": "" }, "400": { "description": "Bad Request: Must select an advisor model." }, "404": { "description": "Not Found: No such advisor model." }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/beneficiaries/": { "get": { "operationId": "participants_beneficiaries_list", "description": "Get a list of a participant's beneficiaries.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Beneficiaries" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "post": { "operationId": "participants_beneficiaries_create", "description": "Create a single or multiple beneficiaries for a participant.\nIf a list is provided, either all or none will be created.", "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": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Beneficiaries" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] }, { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } ] } }, "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] }, { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } ] } }, "multipart/form-data": { "schema": { "oneOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] }, { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } ] } } } }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] }, { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid beneficiary data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "patch": { "operationId": "participants_beneficiaries_partial_update", "description": "Partially update a list of beneficiaries. Each entry must include the `object_id`. The provided list must\nbe a subset of the participant's beneficiaries. Validates every entry first, then either applies all or none of\nthem.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Beneficiaries" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } } } } } }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } }, "description": "" } } } }, "/participants/{participant_id}/beneficiaries/{beneficiary_id}/": { "get": { "operationId": "participants_beneficiaries_retrieve", "description": "Retrieve a specific beneficiary.", "parameters": [ { "in": "path", "name": "beneficiary_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Beneficiaries" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "put": { "operationId": "participants_beneficiaries_update", "description": "Fully update a specific beneficiary.", "parameters": [ { "in": "path", "name": "beneficiary_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Beneficiaries" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid beneficiary data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "patch": { "operationId": "participants_beneficiaries_partial_update_2", "description": "Partially update a single beneficiary.", "parameters": [ { "in": "path", "name": "beneficiary_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Beneficiaries" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } } } } } }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid beneficiary data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "delete": { "operationId": "participants_beneficiaries_destroy", "description": "Delete a beneficiary.", "parameters": [ { "in": "path", "name": "beneficiary_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Beneficiaries" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "204": { "description": "No response body" }, "403": { "description": "Forbidden: Invalid permissions to delete this beneficiary" }, "401": { "description": "Unauthorized: Missing or invalid authentication" } } } }, "/participants/{participant_id}/cancel-participant-rebalance/": { "post": { "operationId": "participants_cancel_participant_rebalance_create", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "is_rebalancing": { "type": "boolean", "readOnly": true }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "can_cancel_rebalance": { "type": "boolean", "readOnly": true }, "next_trading_window": { "type": "string", "format": "date-time", "readOnly": true }, "self_direct_allowed": { "type": "boolean", "readOnly": true }, "opted_in_to_self_direct": { "type": "boolean" } }, "required": [ "can_cancel_rebalance", "is_rebalancing", "next_trading_window", "self_direct_allowed" ] } } }, "description": "" }, "400": { "description": "Bad Request: Rebalance already begun. Unable to cancel" }, "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", "nullable": true, "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,\nmaxing 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", "nullable": true, "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": "" }, "400": { "description": "Bad Request: No active plan associated with this account" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/disbursements/": { "get": { "operationId": "participants_disbursements_list", "description": "Get a list of participant's disbursements.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "Unique identifier for the disbursement." }, "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "status": { "type": "string", "readOnly": true, "description": "The current status of the disbursement (e.g., Pending Approval, Funds Sent, etc.)" }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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" ] } ], "description": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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" ] } ], "description": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "description": "The participant's name" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "description": "The participant's phone number" }, "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" ] } ], "nullable": true, "description": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "object_id", "payment_method", "phone", "reason", "status" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "post": { "operationId": "participants_disbursements_create", "description": "Create a new disbursement request.\nField Usage Patterns:\n1. Single Disbursement (pre-tax only or post-tax only):\n - Use regular fields (payment_method, bank_name, etc.) for payment details\n - Use pretax_memo for pre-tax disbursements\n - Use posttax_memo for post-tax disbursements\n - Use payment_address for pre-tax disbursements\n - Use posttax_payment_address for post-tax disbursements\n\n2. Split Disbursement (both pre-tax and post-tax):\n - Use regular fields (payment_method, bank_name, etc.) for pre-tax portion\n - Use posttax_* fields for post-tax portion if different from pre-tax\n - Both pretax_memo and posttax_memo are required\n - Both payment_address and posttax_payment_address can be specified if different", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "hardship_proof_document": { "type": "string", "format": "byte", "description": "Base64-encoded proof document required for hardship disbursements and death disbursements.", "writeOnly": true }, "hardship_signature": { "type": "string", "format": "byte", "description": "Base64-encoded signature image for hardship disbursements. Recommended dimensions: 500px width x 150px height (10:3 aspect ratio) to match the final document format.", "writeOnly": true }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "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": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "payment_method", "phone", "reason" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "hardship_proof_document": { "type": "string", "format": "byte", "description": "Base64-encoded proof document required for hardship disbursements and death disbursements.", "writeOnly": true }, "hardship_signature": { "type": "string", "format": "byte", "description": "Base64-encoded signature image for hardship disbursements. Recommended dimensions: 500px width x 150px height (10:3 aspect ratio) to match the final document format.", "writeOnly": true }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "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": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "payment_method", "phone", "reason" ] } }, "multipart/form-data": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "hardship_proof_document": { "type": "string", "format": "byte", "description": "Base64-encoded proof document required for hardship disbursements and death disbursements.", "writeOnly": true }, "hardship_signature": { "type": "string", "format": "byte", "description": "Base64-encoded signature image for hardship disbursements. Recommended dimensions: 500px width x 150px height (10:3 aspect ratio) to match the final document format.", "writeOnly": true }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "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": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "payment_method", "phone", "reason" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "Unique identifier for the disbursement." }, "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "status": { "type": "string", "readOnly": true, "description": "The current status of the disbursement (e.g., Pending Approval, Funds Sent, etc.)" }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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" ] } ], "description": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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" ] } ], "description": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "description": "The participant's name" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "description": "The participant's phone number" }, "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" ] } ], "nullable": true, "description": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "object_id", "payment_method", "phone", "reason", "status" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid disbursement data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/disbursements-info/": { "get": { "operationId": "participants_disbursements_info_retrieve", "description": "Get information about available disbursement options before creating one.\n\nQuery parameters can be used to get accurate available amounts for different disbursement types:\n- is_hardship: Calculate amounts for hardship disbursements\n- is_emergency: Calculate amounts for emergency expense disbursements\n- is_move_rollover: Calculate amounts for move rollover disbursements\n\nAll parameters default to false if not specified.", "parameters": [ { "in": "query", "name": "is_emergency", "schema": { "type": "boolean", "default": false }, "description": "Whether to calculate available amounts for emergency expense disbursements." }, { "in": "query", "name": "is_hardship", "schema": { "type": "boolean", "default": false }, "description": "Whether to calculate available amounts for hardship disbursements." }, { "in": "query", "name": "is_move_rollover", "schema": { "type": "boolean", "default": false }, "description": "Whether to calculate available amounts for move rollover disbursements." }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Provides information about available disbursement options before creating a disbursement.", "properties": { "available_reasons": { "type": "array", "items": { "type": "string" }, "description": "List of available disbursement reasons for this participant." }, "missing_reasons": { "type": "object", "additionalProperties": {}, "description": "Dictionary of unavailable reasons with explanations why." }, "pretax_available": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Available pre-tax balance for disbursement." }, "posttax_available": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Available post-tax balance for disbursement." }, "minimum_disbursement": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Minimum allowed disbursement amount." } }, "required": [ "available_reasons", "minimum_disbursement", "missing_reasons", "posttax_available", "pretax_available" ] } } }, "description": "" }, "400": { "description": "Bad Request: Unable to get participant info or invalid query parameters" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/disbursements/{disbursement_id}/": { "get": { "operationId": "participants_disbursements_retrieve", "description": "ViewSet for handling participant disbursements in a single request.", "parameters": [ { "in": "path", "name": "disbursement_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "Unique identifier for the disbursement." }, "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "status": { "type": "string", "readOnly": true, "description": "The current status of the disbursement (e.g., Pending Approval, Funds Sent, etc.)" }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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" ] } ], "description": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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" ] } ], "description": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "description": "The participant's name" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "description": "The participant's phone number" }, "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" ] } ], "nullable": true, "description": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "object_id", "payment_method", "phone", "reason", "status" ] } } }, "description": "" } } }, "put": { "operationId": "participants_disbursements_update", "description": "Update a specific disbursement request.", "parameters": [ { "in": "path", "name": "disbursement_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "hardship_proof_document": { "type": "string", "format": "byte", "description": "Base64-encoded proof document required for hardship disbursements and death disbursements.", "writeOnly": true }, "hardship_signature": { "type": "string", "format": "byte", "description": "Base64-encoded signature image for hardship disbursements. Recommended dimensions: 500px width x 150px height (10:3 aspect ratio) to match the final document format.", "writeOnly": true }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "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": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "payment_method", "phone", "reason" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "hardship_proof_document": { "type": "string", "format": "byte", "description": "Base64-encoded proof document required for hardship disbursements and death disbursements.", "writeOnly": true }, "hardship_signature": { "type": "string", "format": "byte", "description": "Base64-encoded signature image for hardship disbursements. Recommended dimensions: 500px width x 150px height (10:3 aspect ratio) to match the final document format.", "writeOnly": true }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "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": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "payment_method", "phone", "reason" ] } }, "multipart/form-data": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "hardship_proof_document": { "type": "string", "format": "byte", "description": "Base64-encoded proof document required for hardship disbursements and death disbursements.", "writeOnly": true }, "hardship_signature": { "type": "string", "format": "byte", "description": "Base64-encoded signature image for hardship disbursements. Recommended dimensions: 500px width x 150px height (10:3 aspect ratio) to match the final document format.", "writeOnly": true }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "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": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "payment_method", "phone", "reason" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "Unique identifier for the disbursement." }, "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "status": { "type": "string", "readOnly": true, "description": "The current status of the disbursement (e.g., Pending Approval, Funds Sent, etc.)" }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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" ] } ], "description": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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" ] } ], "description": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "description": "The participant's name" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "description": "The participant's phone number" }, "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" ] } ], "nullable": true, "description": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "object_id", "payment_method", "phone", "reason", "status" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid disbursement data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "delete": { "operationId": "participants_disbursements_destroy", "description": "Delete a disbursement request.", "parameters": [ { "in": "path", "name": "disbursement_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "204": { "description": "No response body" }, "400": { "description": "Bad Request: Cannot delete disbursement" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/events/": { "get": { "operationId": "participants_events_retrieve", "description": "Gets a list of the different event types that exist for a participant.\n\nTo check whether a participant's dashboard is accessible, check for the 'completed setup' event.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Participants" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Serializer for participant events.\n\nUsed to get and set event types for a participant. The event types are defined in the ParticipantEvent model.", "properties": { "event_types": { "type": "array", "items": { "enum": [ "Completed Setup", "eDocument Agreement", "Viewed Documents", "Skipped Guided Portfolio", "Remove eDocument Agreement", "Opt Out" ], "type": "string", "description": "* `Completed Setup` - Completed Setup\n* `eDocument Agreement` - eDocument Agreement\n* `Viewed Documents` - Viewed Documents\n* `Skipped Guided Portfolio` - Skipped Guided Portfolio\n* `Remove eDocument Agreement` - Remove eDocument Agreement\n* `Opt Out` - Opt Out", "x-spec-enum-id": "00d31436ce65e13d" }, "minItems": 1 } }, "required": [ "event_types" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "post": { "operationId": "participants_events_create", "description": "Adds a list of the different event types for a participant.\n\nIt will not duplicate events.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Participants" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Serializer for participant events.\n\nUsed to get and set event types for a participant. The event types are defined in the ParticipantEvent model.", "properties": { "event_types": { "type": "array", "items": { "enum": [ "Completed Setup", "eDocument Agreement", "Viewed Documents", "Skipped Guided Portfolio", "Remove eDocument Agreement", "Opt Out" ], "type": "string", "description": "* `Completed Setup` - Completed Setup\n* `eDocument Agreement` - eDocument Agreement\n* `Viewed Documents` - Viewed Documents\n* `Skipped Guided Portfolio` - Skipped Guided Portfolio\n* `Remove eDocument Agreement` - Remove eDocument Agreement\n* `Opt Out` - Opt Out", "x-spec-enum-id": "00d31436ce65e13d" }, "minItems": 1 } }, "required": [ "event_types" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "Serializer for participant events.\n\nUsed to get and set event types for a participant. The event types are defined in the ParticipantEvent model.", "properties": { "event_types": { "type": "array", "items": { "enum": [ "Completed Setup", "eDocument Agreement", "Viewed Documents", "Skipped Guided Portfolio", "Remove eDocument Agreement", "Opt Out" ], "type": "string", "description": "* `Completed Setup` - Completed Setup\n* `eDocument Agreement` - eDocument Agreement\n* `Viewed Documents` - Viewed Documents\n* `Skipped Guided Portfolio` - Skipped Guided Portfolio\n* `Remove eDocument Agreement` - Remove eDocument Agreement\n* `Opt Out` - Opt Out", "x-spec-enum-id": "00d31436ce65e13d" }, "minItems": 1 } }, "required": [ "event_types" ] } }, "multipart/form-data": { "schema": { "type": "object", "description": "Serializer for participant events.\n\nUsed to get and set event types for a participant. The event types are defined in the ParticipantEvent model.", "properties": { "event_types": { "type": "array", "items": { "enum": [ "Completed Setup", "eDocument Agreement", "Viewed Documents", "Skipped Guided Portfolio", "Remove eDocument Agreement", "Opt Out" ], "type": "string", "description": "* `Completed Setup` - Completed Setup\n* `eDocument Agreement` - eDocument Agreement\n* `Viewed Documents` - Viewed Documents\n* `Skipped Guided Portfolio` - Skipped Guided Portfolio\n* `Remove eDocument Agreement` - Remove eDocument Agreement\n* `Opt Out` - Opt Out", "x-spec-enum-id": "00d31436ce65e13d" }, "minItems": 1 } }, "required": [ "event_types" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/investment-history/": { "get": { "operationId": "participants_investment_history_list", "description": "Get a list of investment transactions for the given participant id.\n\nYou can optionally paginate by including 'page={page_num}&page_size={page_size}' in the query string.\nPossible statuses: pending, confirmed, failed, dividend.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "investment": { "allOf": [ { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } ], "readOnly": true }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,4})?$" }, "share_price": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,9})?$" }, "amount_paid": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,14}(?:\\.\\d{0,2})?$" }, "settle_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "readOnly": true }, "money_sources": { "type": "array", "items": { "type": "object", "properties": { "money_source": { "type": "string", "enum": [ "Employee Deferral", "Discretionary Non Elective (Profit Sharing)", "Safe Harbor Non Elective", "Discretionary Match", "Safe Harbor Match", "Correction Contribution (QMAC)", "Qualified Non-Elective Contribution", "Rollover", "Other", "Individual Contribution", "Conversion" ] }, "tax_type": { "type": "string", "enum": [ "Pre-tax", "Post-tax" ] }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,9})?$" } }, "required": [ "money_source", "shares", "tax_type" ] }, "readOnly": true } }, "required": [ "amount_paid", "investment", "money_sources", "object_id", "share_price", "shares", "status" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/investment-options/": { "get": { "operationId": "participants_investment_options_list", "description": "Get a list of investment options available to the given participant.\n\nYou can optionally paginate by including 'page={page_num}&page_size={page_size}' in the query string.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `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" } } } }, "/participants/{participant_id}/investment-performance/": { "get": { "operationId": "participants_investment_performance_list", "description": "Get a list of portfolios - one for each day between two dates.", "parameters": [ { "in": "query", "name": "end_date", "schema": { "type": "string" }, "description": "End date for filtering portfolios (YYYY-MM-DD format). Defaults to today." }, { "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "start_date", "schema": { "type": "string" }, "description": "Start date for filtering portfolios (YYYY-MM-DD format). Defaults to the first day an investment transaction occurred." } ], "tags": [ "Investments & Portfolios" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "Portfolio information for a single day.", "properties": { "investments": { "type": "array", "items": { "type": "object", "description": "Investment information for a single day in portfolio history.", "properties": { "object_id": { "type": "string", "description": "The object_id of the associated Investment" }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,3})?$" }, "share_price": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,9})?$" }, "basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "proceeds": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "basis", "object_id", "proceeds", "share_price", "shares" ] } }, "date": { "type": "string", "format": "date" }, "cash": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "cash", "date", "investments" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/loan-requests/": { "get": { "operationId": "participants_loan_requests_list", "description": "Get a list of a participant's loan requests.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "A loan request for a participant.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "description": "Not required if is_primary_residence is true", "maxLength": 200, "minLength": 5 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer" }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "date": { "type": "string", "readOnly": true }, "interest_rate": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,10})?$", "readOnly": true }, "balance": { "type": "string", "readOnly": true }, "period_payment": { "type": "string", "readOnly": true }, "promissory_note_url": { "type": "string", "readOnly": true }, "fee_amount": { "type": "string", "readOnly": true }, "wire_transfer_fee": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "Active", "Reamortized", "Closed", "Past Due", "In Default", "Deemed Distribution", "Not Complete", "Requested", "Approved", "Canceled", "Denied", "Needs Amortization Approval" ], "readOnly": true, "description": "A signature is still required if not \"Requested\"" } }, "required": [ "address", "balance", "date", "dob", "fee_amount", "interest_rate", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "object_id", "payment_method", "period_payment", "phone", "promissory_note_url", "status", "wire_transfer_fee" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "post": { "operationId": "participants_loan_requests_create", "description": "Create a loan request.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "minLength": 5, "description": "Not required if is_primary_residence is true", "maxLength": 200 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer", "minimum": 1 }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" } }, "required": [ "address", "dob", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "payment_method", "phone" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "minLength": 5, "description": "Not required if is_primary_residence is true", "maxLength": 200 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer", "minimum": 1 }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" } }, "required": [ "address", "dob", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "payment_method", "phone" ] } }, "multipart/form-data": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "minLength": 5, "description": "Not required if is_primary_residence is true", "maxLength": 200 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer", "minimum": 1 }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" } }, "required": [ "address", "dob", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "payment_method", "phone" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "description": "Not required if is_primary_residence is true", "maxLength": 200, "minLength": 5 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer" }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "date": { "type": "string", "readOnly": true }, "interest_rate": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,10})?$", "readOnly": true }, "balance": { "type": "string", "readOnly": true }, "period_payment": { "type": "string", "readOnly": true }, "promissory_note_url": { "type": "string", "readOnly": true }, "fee_amount": { "type": "string", "readOnly": true }, "wire_transfer_fee": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "Active", "Reamortized", "Closed", "Past Due", "In Default", "Deemed Distribution", "Not Complete", "Requested", "Approved", "Canceled", "Denied", "Needs Amortization Approval" ], "readOnly": true, "description": "A signature is still required if not \"Requested\"" } }, "required": [ "address", "balance", "date", "dob", "fee_amount", "interest_rate", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "object_id", "payment_method", "period_payment", "phone", "promissory_note_url", "status", "wire_transfer_fee" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid loan request data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/loan-requests-info/": { "get": { "operationId": "participants_loan_requests_info_retrieve", "description": "Get information that is useful before beginning a loan request.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "can_take_loan": { "type": "boolean" }, "cannot_take_reason": { "type": "string", "nullable": true }, "fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "wire_transfer_fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "available_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "available_amount", "can_take_loan", "cannot_take_reason", "fee_amount", "wire_transfer_fee" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/loan-requests-signature/{loan_request_id}/": { "put": { "operationId": "participants_loan_requests_signature_update", "description": "Submit a signature for this loan request.", "parameters": [ { "in": "path", "name": "loan_request_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Submit a signature for a loan request.", "properties": { "signature": { "type": "string", "format": "byte", "description": "Base64-encoded image data", "writeOnly": true } }, "required": [ "signature" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "Submit a signature for a loan request.", "properties": { "signature": { "type": "string", "format": "byte", "description": "Base64-encoded image data", "writeOnly": true } }, "required": [ "signature" ] } }, "multipart/form-data": { "schema": { "type": "object", "description": "Submit a signature for a loan request.", "properties": { "signature": { "type": "string", "format": "byte", "description": "Base64-encoded image data", "writeOnly": true } }, "required": [ "signature" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Submit a signature for a loan request.", "properties": { "promissory_note_url": { "type": "string", "readOnly": true } }, "required": [ "promissory_note_url" ] } } }, "description": "" }, "400": { "description": "Bad Request: invalid update" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/loan-requests/{loan_request_id}/": { "get": { "operationId": "participants_loan_requests_retrieve", "description": "Retrieve a specific loan request.", "parameters": [ { "in": "path", "name": "loan_request_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "description": "Not required if is_primary_residence is true", "maxLength": 200, "minLength": 5 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer" }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "date": { "type": "string", "readOnly": true }, "interest_rate": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,10})?$", "readOnly": true }, "balance": { "type": "string", "readOnly": true }, "period_payment": { "type": "string", "readOnly": true }, "promissory_note_url": { "type": "string", "readOnly": true }, "fee_amount": { "type": "string", "readOnly": true }, "wire_transfer_fee": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "Active", "Reamortized", "Closed", "Past Due", "In Default", "Deemed Distribution", "Not Complete", "Requested", "Approved", "Canceled", "Denied", "Needs Amortization Approval" ], "readOnly": true, "description": "A signature is still required if not \"Requested\"" } }, "required": [ "address", "balance", "date", "dob", "fee_amount", "interest_rate", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "object_id", "payment_method", "period_payment", "phone", "promissory_note_url", "status", "wire_transfer_fee" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "put": { "operationId": "participants_loan_requests_update", "description": "Fully update a specific loan request.", "parameters": [ { "in": "path", "name": "loan_request_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "minLength": 5, "description": "Not required if is_primary_residence is true", "maxLength": 200 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer", "minimum": 1 }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" } }, "required": [ "address", "dob", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "payment_method", "phone" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "minLength": 5, "description": "Not required if is_primary_residence is true", "maxLength": 200 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer", "minimum": 1 }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" } }, "required": [ "address", "dob", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "payment_method", "phone" ] } }, "multipart/form-data": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "minLength": 5, "description": "Not required if is_primary_residence is true", "maxLength": 200 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer", "minimum": 1 }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" } }, "required": [ "address", "dob", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "payment_method", "phone" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "A loan request for a participant.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "description": "Not required if is_primary_residence is true", "maxLength": 200, "minLength": 5 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer" }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "date": { "type": "string", "readOnly": true }, "interest_rate": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,10})?$", "readOnly": true }, "balance": { "type": "string", "readOnly": true }, "period_payment": { "type": "string", "readOnly": true }, "promissory_note_url": { "type": "string", "readOnly": true }, "fee_amount": { "type": "string", "readOnly": true }, "wire_transfer_fee": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "Active", "Reamortized", "Closed", "Past Due", "In Default", "Deemed Distribution", "Not Complete", "Requested", "Approved", "Canceled", "Denied", "Needs Amortization Approval" ], "readOnly": true, "description": "A signature is still required if not \"Requested\"" } }, "required": [ "address", "balance", "date", "dob", "fee_amount", "interest_rate", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "object_id", "payment_method", "period_payment", "phone", "promissory_note_url", "status", "wire_transfer_fee" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid loan request data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "delete": { "operationId": "participants_loan_requests_destroy", "description": "Delete a loan request.", "parameters": [ { "in": "path", "name": "loan_request_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "204": { "description": "No response body" }, "400": { "description": "Bad Request: Cannot delete processed loan" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/matches/": { "get": { "operationId": "participants_matches_retrieve", "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": { "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" ] } ], "nullable": true }, "nondiscretionary_nonelective": { "allOf": [ { "type": "object", "properties": { "contribution_rate": { "type": "integer" } }, "required": [ "contribution_rate" ] } ], "nullable": true } }, "required": [ "discretionary_matches", "discretionary_nonelective", "nondiscretionary_nonelective", "plan_matches" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/money-movement-history/": { "get": { "operationId": "participants_money_movement_history_list", "description": "Get a list of money movement transactions for the given participant id.\n\nThe account type will be Pre-tax for employee pre-tax movements, Post-tax for employee post-tax movements,\nVested Contribution for any vested employer contributions, Non-vested Contribution for any non-vested employer contributions.\nThe tax_type field is only really useful to distinguish pre-tax or post-tax employer contributions when it has a value.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "memo": { "type": "string", "maxLength": 200 }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,12}(?:\\.\\d{0,8})?$" }, "movement_type": { "enum": [ "Employee Deferral", "Non-roth After Tax Deferral", "Rollover", "Dividend", "Discretionary Non Elective (Profit Sharing)", "Safe Harbor Non Elective", "Discretionary Match", "Safe Harbor Match", "Correction Contribution (QMAC)", "Qualified Non-Elective Contribution", "Loan Interest", "Disbursement", "Correction Disbursement", "Lost Earnings Contribution", "Transferred Earnings", "Loan", "Fee", "Other" ], "type": "string", "description": "* `Employee Deferral` - Employee Deferral\n* `Non-roth After Tax Deferral` - Non-roth After Tax Deferral\n* `Rollover` - Rollover\n* `Dividend` - Dividend\n* `Discretionary Non Elective (Profit Sharing)` - Discretionary Non Elective (Profit Sharing)\n* `Safe Harbor Non Elective` - Safe Harbor Non Elective\n* `Discretionary Match` - Discretionary Match\n* `Safe Harbor Match` - Safe Harbor Match\n* `Correction Contribution (QMAC)` - Correction Contribution (QMAC)\n* `Qualified Non-Elective Contribution` - Qualified Non-Elective Contribution\n* `Loan Interest` - Loan Interest\n* `Disbursement` - Disbursement\n* `Correction Disbursement` - Correction Disbursement\n* `Lost Earnings Contribution` - Lost Earnings Contribution\n* `Transferred Earnings` - Transferred Earnings\n* `Loan` - Loan\n* `Fee` - Fee\n* `Other` - Other", "x-spec-enum-id": "c7efb0d4aff775fd" }, "applied_date": { "type": "string", "format": "date", "nullable": true }, "account_type": { "enum": [ "Pre-tax", "Post-tax", "Vested Contribution", "Non-vested Contribution" ], "type": "string", "description": "* `Pre-tax` - Pre-tax\n* `Post-tax` - Post-tax\n* `Vested Contribution` - Vested Contribution\n* `Non-vested Contribution` - Non-vested Contribution", "x-spec-enum-id": "5548afd0b1c14da0" }, "tax_type": { "enum": [ "Pre-tax", "Post-tax" ], "type": "string", "description": "* `Pre-tax` - Pre-tax\n* `Post-tax` - Post-tax", "x-spec-enum-id": "40e39026ee7fdc9a" }, "testing_exempt": { "type": "boolean" } }, "required": [ "account_type", "movement_type", "object_id" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/notifications/": { "get": { "operationId": "participants_notifications_list", "description": "Get a list of notifications for a participant.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Notifications" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "subject": { "type": "string", "readOnly": true }, "notification_content": { "type": "string", "readOnly": true }, "content_is_html": { "type": "boolean", "readOnly": true }, "status": { "type": "string", "enum": [ "New", "Viewed", "Archived" ] }, "timestamp": { "type": "string", "format": "date-time", "readOnly": true }, "attachment": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "name", "object_id" ] }, "readOnly": true }, "signed_url": { "type": "string", "description": "Get signed URL for attachments if needed.", "readOnly": true } }, "required": [ "attachment", "content_is_html", "notification_content", "object_id", "signed_url", "status", "subject", "timestamp" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/notifications/{notification_id}/": { "patch": { "operationId": "participants_notifications_partial_update", "parameters": [ { "in": "path", "name": "notification_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Notifications" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "New", "Viewed", "Archived" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "New", "Viewed", "Archived" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "New", "Viewed", "Archived" ] } } } } } }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "subject": { "type": "string", "readOnly": true }, "notification_content": { "type": "string", "readOnly": true }, "content_is_html": { "type": "boolean", "readOnly": true }, "status": { "type": "string", "enum": [ "New", "Viewed", "Archived" ] }, "timestamp": { "type": "string", "format": "date-time", "readOnly": true }, "attachment": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "name", "object_id" ] }, "readOnly": true }, "signed_url": { "type": "string", "description": "Get signed URL for attachments if needed.", "readOnly": true } }, "required": [ "attachment", "content_is_html", "notification_content", "object_id", "signed_url", "status", "subject", "timestamp" ] } } }, "description": "" } } } }, "/participants/{participant_id}/notifications/attachment/{attachment_id}/": { "get": { "operationId": "participants_notifications_attachment_retrieve", "description": "Returns a signed url for the given attachment that will last for 30 minutes.", "parameters": [ { "in": "path", "name": "attachment_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Notifications" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Serializer for document signed URLs.", "properties": { "signed_url": { "type": "string", "format": "uri" } }, "required": [ "signed_url" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/participant-documents/": { "get": { "operationId": "list_participant_documents", "description": "Returns a list of participant related documents.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Documents" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Serializer for listing available documents for a participant.", "properties": { "available_documents": { "type": "array", "items": { "enum": [ "plan_document", "plan_highlights", "fee_disclosures", "qdia", "safe_harbor_notice", "auto_enroll_notice" ], "type": "string", "description": "* `plan_document` - plan_document\n* `plan_highlights` - plan_highlights\n* `fee_disclosures` - fee_disclosures\n* `qdia` - qdia\n* `safe_harbor_notice` - safe_harbor_notice\n* `auto_enroll_notice` - auto_enroll_notice", "x-spec-enum-id": "9778ac1b6a16c5cc" } } }, "required": [ "available_documents" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/participant-documents/{document_name}/": { "get": { "operationId": "get_signed_participant_document_url", "description": "Returns a signed url for the given named document that will last for 30 minutes.", "parameters": [ { "in": "path", "name": "document_name", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Documents" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Serializer for document signed URLs.", "properties": { "signed_url": { "type": "string", "format": "uri" } }, "required": [ "signed_url" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid document name or document not available for this participant" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/participant-setup/": { "get": { "operationId": "participants_participant_setup_retrieve", "description": "Gets plan data for the associated participant, and if they've set their deferral elections.\n\nChoices for 'plan_type' are 'Volume Submitter Prototype Format' (401k plans), '403B', and 'Starter-K'", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Participants" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Serializer for participant setup information including plan details and deferral status.", "properties": { "eligibility_date": { "type": "string", "format": "date" }, "has_deferrals": { "type": "boolean" }, "plan_name": { "type": "string" }, "plan_type": { "type": "string" }, "plan_number": { "type": "integer" }, "plan_allow_self_direct": { "type": "boolean" }, "opted_to_self_direct": { "type": "boolean" }, "auto_enroll_percent": { "type": "string", "nullable": true, "default": "5", "maxLength": 2 }, "has_eDocs_agreement": { "type": "boolean" } }, "required": [ "eligibility_date", "has_deferrals", "has_eDocs_agreement", "opted_to_self_direct", "plan_allow_self_direct", "plan_name", "plan_number", "plan_type" ] } } }, "description": "" }, "400": { "description": "Bad Request: No active plan associated with this account" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/payroll-lines/": { "get": { "operationId": "participants_payroll_lines_list", "description": "Get the payroll lines for a participant.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Contributions & Payroll" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "A payroll line represents payroll for one participant and has the associated id of that participant.\n\nIt 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.\n\nCurrently, 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\n* `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" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/portfolio/": { "get": { "operationId": "participants_portfolio_list", "description": "Gets a list of portfolio investments for the given participant.\n\n### Investment states\n- `ACTIVE`: Investment is part of the portfolio.\n- `PENDING_SALE`: Investment has been removed from the portfolio and is being fully liquidated.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "investment": { "allOf": [ { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } ], "readOnly": true }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "value": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "status": { "enum": [ "PENDING_SALE", "ACTIVE" ], "type": "string", "description": "* `PENDING_SALE` - Pending Sale\n* `ACTIVE` - Active", "x-spec-enum-id": "a442a24a44038e9a", "readOnly": true } }, "required": [ "investment", "percent", "shares", "status", "value" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "post": { "operationId": "participants_portfolio_create", "description": "Updates a participant's target portfolio allocations.\n\nExpects:\n- `investments`: list of investment ids\n- `weights`: list of target percent weights (aligned by index with `investments`)\n\n### 0% allocations\nSetting an investment target allocation to `0%` does **not** remove it from the portfolio. If `auto_rebalance` is disabled,\nno trades will occur until a manual rebalance is triggered.\n\n### Removing an investment\nAny allocation you specify in a POST request replaces any prior allocation.\nThus, to remove an investment from the portfolio, simply post an allocation without that investment.\nOnce an investment is removed from the portfolio, the system will sell all shares of that investment\n**regardless of whether `auto_rebalance` is enabled**. Removed investments enter `PENDING_SALE` until liquidation is complete.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "investments": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "List of investment IDs" }, "weights": { "type": "array", "items": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,6}(?:\\.\\d{0,6})?$" }, "description": "List of investment weights. The order of weights must parallel the order of investments." } }, "required": [ "investments", "weights" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "investments": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "List of investment IDs" }, "weights": { "type": "array", "items": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,6}(?:\\.\\d{0,6})?$" }, "description": "List of investment weights. The order of weights must parallel the order of investments." } }, "required": [ "investments", "weights" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "investments": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "List of investment IDs" }, "weights": { "type": "array", "items": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,6}(?:\\.\\d{0,6})?$" }, "description": "List of investment weights. The order of weights must parallel the order of investments." } }, "required": [ "investments", "weights" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "investment": { "allOf": [ { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } ], "readOnly": true }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "value": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "status": { "enum": [ "PENDING_SALE", "ACTIVE" ], "type": "string", "description": "* `PENDING_SALE` - Pending Sale\n* `ACTIVE` - Active", "x-spec-enum-id": "a442a24a44038e9a", "readOnly": true } }, "required": [ "investment", "percent", "shares", "status", "value" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/portfolio-settings/": { "get": { "operationId": "participants_portfolio_settings_retrieve", "description": "Get data points related to rebalancing, trading windows, and if a participant can self direct.\n\ncan_cancel_rebalance represents if the current time is in a trading window.\nThe next_trading_window returns the start of the next trading window and should be used with caution,\npreferably with a buffer of about 30 minutes for if the trade can be completed in this time.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "is_rebalancing": { "type": "boolean", "readOnly": true }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "can_cancel_rebalance": { "type": "boolean", "readOnly": true }, "next_trading_window": { "type": "string", "format": "date-time", "readOnly": true }, "self_direct_allowed": { "type": "boolean", "readOnly": true }, "opted_in_to_self_direct": { "type": "boolean" } }, "required": [ "can_cancel_rebalance", "is_rebalancing", "next_trading_window", "self_direct_allowed" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "post": { "operationId": "participants_portfolio_settings_create", "description": "Updates a participant's option to auto rebalance, rebalance percent, and if they have opted in to self direct", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "opted_in_to_self_direct": { "type": "boolean" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "opted_in_to_self_direct": { "type": "boolean" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "opted_in_to_self_direct": { "type": "boolean" } } } } } }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "is_rebalancing": { "type": "boolean", "readOnly": true }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "can_cancel_rebalance": { "type": "boolean", "readOnly": true }, "next_trading_window": { "type": "string", "format": "date-time", "readOnly": true }, "self_direct_allowed": { "type": "boolean", "readOnly": true }, "opted_in_to_self_direct": { "type": "boolean" } }, "required": [ "can_cancel_rebalance", "is_rebalancing", "next_trading_window", "self_direct_allowed" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/retirement-planning-defaults/": { "get": { "operationId": "participants_retirement_planning_defaults_retrieve", "description": "Get the defaults used for the estimation. Note that the defaults returned may not be valid for getting an\nestimate, for example if `age > retirement_age`.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Retirement Planning" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "age": { "type": "integer", "maximum": 115, "minimum": 18, "description": "Defaults to participant's age" }, "retirement_age": { "type": "integer", "maximum": 115, "minimum": 18, "description": "Defaults to participant's retirement age" }, "salary": { "type": "integer", "minimum": 0, "description": "Defaults to participant's previous year compensation or estimation based on this year" }, "current_savings": { "type": "integer", "minimum": 0, "description": "Defaults to participant's current account balance" }, "savings_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Percentage of income saved" }, "annual_raise": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "2.00", "description": "Expected annual raise" }, "inflation": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "2.00", "description": "Expected annual inflation" }, "correct_for_inflation": { "type": "boolean", "default": true, "description": "Display amounts as they are worth today" }, "investment_return": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "5.00", "description": "Expected annual investment return" }, "life_expectancy": { "type": "integer", "default": 90 }, "retirement_spending": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "70.00", "description": "Percentage of income needed during retirement" }, "include_contributions": { "type": "boolean", "default": true, "description": "Include employer contributions to the account" }, "include_social_security": { "type": "boolean", "default": true }, "under_50_contribution_limit": { "type": "integer", "readOnly": true }, "over_50_contribution_limit": { "type": "integer", "readOnly": true } }, "required": [ "over_50_contribution_limit", "under_50_contribution_limit" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/retirement-planning-estimate/": { "get": { "operationId": "participants_retirement_planning_estimate_list", "description": "Estimate a participant's projected balance and target savings for retirement. Will use the defaults as defined\nfrom the retirement-planning-defaults unless an override is given. Can only be used if the participant has not\nyet reached retirement, or the supplied `age` is less than `retirement_age`.", "parameters": [ { "in": "query", "name": "age", "schema": { "type": "integer", "maximum": 115, "minimum": 18 }, "description": "Defaults to participant's age" }, { "in": "query", "name": "annual_raise", "schema": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "2.00" }, "description": "Expected annual raise" }, { "in": "query", "name": "correct_for_inflation", "schema": { "type": "boolean", "default": true }, "description": "Display amounts as they are worth today" }, { "in": "query", "name": "current_savings", "schema": { "type": "integer", "minimum": 0 }, "description": "Defaults to participant's current account balance" }, { "in": "query", "name": "include_contributions", "schema": { "type": "boolean", "default": true }, "description": "Include employer contributions to the account" }, { "in": "query", "name": "include_social_security", "schema": { "type": "boolean", "default": true } }, { "in": "query", "name": "inflation", "schema": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "2.00" }, "description": "Expected annual inflation" }, { "in": "query", "name": "investment_return", "schema": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "5.00" }, "description": "Expected annual investment return" }, { "in": "query", "name": "life_expectancy", "schema": { "type": "integer", "default": 90 } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "retirement_age", "schema": { "type": "integer", "maximum": 115, "minimum": 18 }, "description": "Defaults to participant's retirement age" }, { "in": "query", "name": "retirement_spending", "schema": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "70.00" }, "description": "Percentage of income needed during retirement" }, { "in": "query", "name": "salary", "schema": { "type": "integer", "minimum": 0 }, "description": "Defaults to participant's previous year compensation or estimation based on this year" }, { "in": "query", "name": "savings_percent", "schema": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$" }, "description": "Percentage of income saved" } ], "tags": [ "Retirement Planning" ], "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "age": { "type": "integer" }, "estimated_balance": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "target_savings": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "social_security": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$", "nullable": true, "description": "Estimated annual amount of social security received. This figure is already included into the estimated_balance." } }, "required": [ "age", "estimated_balance", "social_security", "target_savings" ] } } } }, "description": "" }, "400": { "description": "Bad Request: invalid supplied data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/rollovers/": { "get": { "operationId": "participants_rollovers_list", "description": "Get a list of participant's rollovers.", "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" } }, { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "Incomplete", "Submitted", "Funds Received", "Abandoned" ], "readOnly": true }, "rollover_acceptance_letter_url": { "type": "string", "readOnly": true } }, "required": [ "address", "dob", "married", "name", "object_id", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "rollover_acceptance_letter_url", "status", "total_rollover_amount" ] } } } } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "post": { "operationId": "participants_rollovers_create", "description": "Create a new rollover in one single request.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "minLength": 1, "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false } }, "required": [ "address", "dob", "married", "name", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "total_rollover_amount" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "minLength": 1, "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false } }, "required": [ "address", "dob", "married", "name", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "total_rollover_amount" ] } }, "multipart/form-data": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "minLength": 1, "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false } }, "required": [ "address", "dob", "married", "name", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "total_rollover_amount" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "Incomplete", "Submitted", "Funds Received", "Abandoned" ], "readOnly": true }, "rollover_acceptance_letter_url": { "type": "string", "readOnly": true } }, "required": [ "address", "dob", "married", "name", "object_id", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "rollover_acceptance_letter_url", "status", "total_rollover_amount" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid rollover data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/rollovers/{rollover_id}/": { "get": { "operationId": "participants_rollovers_retrieve", "description": "Retrieve a specific rollover request.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "rollover_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "Incomplete", "Submitted", "Funds Received", "Abandoned" ], "readOnly": true }, "rollover_acceptance_letter_url": { "type": "string", "readOnly": true } }, "required": [ "address", "dob", "married", "name", "object_id", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "rollover_acceptance_letter_url", "status", "total_rollover_amount" ] } } }, "description": "" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "put": { "operationId": "participants_rollovers_update", "description": "Update a specific rollover request.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "rollover_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "minLength": 1, "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false } }, "required": [ "address", "dob", "married", "name", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "total_rollover_amount" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "minLength": 1, "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false } }, "required": [ "address", "dob", "married", "name", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "total_rollover_amount" ] } }, "multipart/form-data": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "minLength": 1, "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false } }, "required": [ "address", "dob", "married", "name", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "total_rollover_amount" ] } } }, "required": true }, "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "Incomplete", "Submitted", "Funds Received", "Abandoned" ], "readOnly": true }, "rollover_acceptance_letter_url": { "type": "string", "readOnly": true } }, "required": [ "address", "dob", "married", "name", "object_id", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "rollover_acceptance_letter_url", "status", "total_rollover_amount" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid rollover data" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } }, "delete": { "operationId": "participants_rollovers_destroy", "description": "Delete a rollover request.", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "rollover_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Money Movement" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "204": { "description": "No response body" }, "400": { "description": "Bad Request: Cannot delete rollover" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/start-participant-rebalance/": { "post": { "operationId": "participants_start_participant_rebalance_create", "parameters": [ { "in": "path", "name": "participant_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Investments & Portfolios" ], "security": [ { "oauth2": [] }, { "knoxApiToken": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "is_rebalancing": { "type": "boolean", "readOnly": true }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "can_cancel_rebalance": { "type": "boolean", "readOnly": true }, "next_trading_window": { "type": "string", "format": "date-time", "readOnly": true }, "self_direct_allowed": { "type": "boolean", "readOnly": true }, "opted_in_to_self_direct": { "type": "boolean" } }, "required": [ "can_cancel_rebalance", "is_rebalancing", "next_trading_window", "self_direct_allowed" ] } } }, "description": "" }, "400": { "description": "Bad Request: Manual rebalance not possible when auto-rebalance is enabled" }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/participants/{participant_id}/totals/": { "get": { "operationId": "participants_totals_retrieve", "description": "Returns year-to-date contribution totals, account balances, income, loans,\nand applicable annual contribution limits.\n\nIncludes YTD totals for:\n- Pre-tax contributions\n- Post-tax contributions\n- Company contributions\n- Compensation (YTD and prior year)\n\nAlso includes:\n- Total account balance\n- Cash balance\n- Active loan balances\n- Payroll count for the year\n\nContribution limits:\n\n- Pre-tax and post-tax contributions share a single combined\n contribution limit.\n This means contributions to EITHER pre-tax OR post-tax reduce\n the remaining limit for BOTH.\n\n Example:\n If the contribution limit is $23,000 and a participant contributes\n $10,000 pre-tax, they can contribute at most $13,000 more total\n across pre-tax and post-tax combined.\n\n- Catch-up contributions have special eligibility rules.\n A participant may be eligible for Roth (post-tax) catch-up\n without being eligible for traditional (pre-tax) catch-up.\n\n- The `year_contribution_limit` is the absolute maximum for all\n contributions combined:\n pre-tax + post-tax + all catch-up contributions.\n\n- Each contribution type may not exceed its own individual limit.", "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": { "pretax_ytd": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true }, "posttax_ytd": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true }, "company_contributions_ytd": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true }, "annual_income": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Expected total annual income based on prior years." }, "annual_income_ytd": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Annual income earned year-to-date." }, "total_balance": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Total account balance, including all investments and cash." }, "cash_balance": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Cash balance in the account." }, "year_payroll_count": { "type": "integer", "minimum": 0.0, "description": "Number of expected payrolls in a year." }, "loans": { "type": "array", "items": { "type": "object", "properties": { "loan_balance": { "type": "number", "format": "double", "readOnly": true }, "issue_date": { "type": "string", "format": "date" }, "first_payment_date": { "type": "string", "format": "date", "nullable": true }, "years_duration": { "type": "integer", "readOnly": true } }, "required": [ "first_payment_date", "issue_date", "loan_balance", "years_duration" ] } }, "year_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Participant contribution limits for the year." }, "pre_tax_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Pre-tax contribution limits for the year." }, "post_tax_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Post-tax contribution limits for the year." }, "pre_tax_catch_up_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Pre-tax catch-up contribution limits for the year." }, "post_tax_catch_up_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Post-tax catch-up contribution limits for the year." } }, "required": [ "annual_income", "annual_income_ytd", "cash_balance", "company_contributions_ytd", "loans", "posttax_ytd", "pretax_ytd", "total_balance", "year_payroll_count" ] } } }, "description": "" }, "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.\n\nReturns an ``object_id`` identifying the new company/plan. Use it as the path parameter for\nsubsequent PUT/PATCH requests to update the plan.\n\n**Fields requiring IDs from other endpoints**\n\nSeveral fields accept opaque IDs that must first be retrieved from other API endpoints:\n\n- ``acting_338``: retrieve from the *Affiliate Firms > Affiliates* or *Affiliates* endpoint.\n- ``pooled_plan``: retrieve from the *Affiliate Firms > Pooled Plans* endpoint.\n- ``billing_tier``: retrieve from the *Affiliate Firms > Pricing Tiers* or *Affiliates > Pricing Tiers* endpoint.\n- ``fund_lineup``: retrieve from the *Affiliate Firms > Fund Lineups* endpoint.\n\n**Mutually exclusive fields**\n\n- ``pooled_plan`` and ``acting_338``: provide **at most one**.\n- ``employer_match_tiers`` and ``non_elective_contribution``: provide **at most one**.\n\n**Fields that must be provided together**\n\n- ``plan_type`` and ``plan_effective_date``: provide **both or neither**.\n- ``payroll_frequency`` and ``next_payroll_date``: provide **both or neither**.\n- ``grandfather_existing_employees`` requires ``plan_effective_date``.\n\n**Fields that depend on other fields**\n\n- ``billing_tier`` and ``fund_lineup`` each require ``acting_338`` or ``pooled_plan``.\n- ``automatic_escalation_cap`` requires a non-zero ``automatic_enrollment_percentage``.\n- ``safe_harbor_exclude_hce_and_key`` is only valid for safe harbor plan types.\n- ``vesting_schedule`` requires ``plan_type``.\n\n**Plan type and employer contribution rules**\n\nEach plan type enforces specific rules for ``employer_match_tiers`` and ``non_elective_contribution``:\n\n- **Basic Safe Harbor**: match must follow the standard formula exactly: 100% of the first 3%, then 50% of the next 2% (up to 5%).\n- **Enhanced Safe Harbor**: one match tier; total match must be a whole number between 4% and 6%.\n- **Safe Harbor Non-Elective**: use ``non_elective_contribution`` (3–6%); do not provide ``employer_match_tiers``.\n- **QACA Safe Harbor**: total match must be between 3.5% and 6%.\n- **Traditional / Starter K / Solo K**: one match tier; total match must be a whole number between 0% and 10%.\n\n**Plan effective date**\n\nMust generally fall on or after the first of the following month. Exception: during December–February,\nTraditional, Solo K, and Safe Harbor Non-Elective plans may use December 1st as their effective date.\n\n**EIN**\n\nOnly new plans are supported. If the EIN is already on the platform, the request will be rejected.\nTakeover 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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "minLength": 1, "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "minLength": 1, "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "primary_contact_email", "primary_contact_name" ] } }, "application/x-www-form-urlencoded": { "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "minLength": 1, "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "minLength": 1, "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "primary_contact_email", "primary_contact_name" ] } }, "multipart/form-data": { "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "minLength": 1, "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "minLength": 1, "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "primary_contact_email", "primary_contact_name" ] } } }, "required": true }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Serializer for plan provisions and settings. Creates both a company and a plan on POST.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "ID for the created or updated company. Use this as the path parameter for subsequent PUT requests to update the plan." }, "company_name": { "type": "string", "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", "description": "Email address of the company's primary contact.", "maxLength": 254 }, "primary_contact_name": { "type": "string", "description": "Full name of the company's primary contact.", "maxLength": 75 }, "ein": { "type": "string", "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", "description": "Full name of the plan trustee.", "maxLength": 250 }, "trustee_email": { "type": "string", "format": "email", "description": "Email address of the plan trustee.", "maxLength": 250 }, "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" ] } ], "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", "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "object_id", "primary_contact_email", "primary_contact_name" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid plan setup data." }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } }, "/plan-setup/{company_id}/": { "put": { "operationId": "plan_setup_update", "description": "Updates an existing 401(k) plan.\n\nThe ``{id}`` path parameter is the ``object_id`` returned from the POST response.\n\nPartial updates (PATCH) will not work. Endpoint currently only supports full replacement (PUT).\n\nUpdates are blocked if the plan has been modified through the web portal after initial\nAPI setup, or if the plan is or was active.", "parameters": [ { "in": "path", "name": "company_id", "schema": { "type": "string" }, "required": true } ], "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "minLength": 1, "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "minLength": 1, "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "primary_contact_email", "primary_contact_name" ] } }, "application/x-www-form-urlencoded": { "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "minLength": 1, "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "minLength": 1, "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "primary_contact_email", "primary_contact_name" ] } }, "multipart/form-data": { "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "minLength": 1, "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "minLength": 1, "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "primary_contact_email", "primary_contact_name" ] } } }, "required": true }, "security": [ { "oauth2": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "description": "Serializer for plan provisions and settings. Creates both a company and a plan on POST.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "ID for the created or updated company. Use this as the path parameter for subsequent PUT requests to update the plan." }, "company_name": { "type": "string", "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", "description": "Email address of the company's primary contact.", "maxLength": 254 }, "primary_contact_name": { "type": "string", "description": "Full name of the company's primary contact.", "maxLength": 75 }, "ein": { "type": "string", "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", "description": "Full name of the plan trustee.", "maxLength": 250 }, "trustee_email": { "type": "string", "format": "email", "description": "Email address of the plan trustee.", "maxLength": 250 }, "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" ] } ], "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", "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "object_id", "primary_contact_email", "primary_contact_name" ] } } }, "description": "" }, "400": { "description": "Bad Request: Invalid plan setup data." }, "401": { "description": "Unauthorized: Missing or invalid authentication" }, "403": { "description": "Forbidden: Insufficient permissions or scopes" } } } } }, "components": { "schemas": { "Address": { "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" ] }, "AddressRequest": { "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" ] }, "Affiliate": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string" }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "address", "crd", "name", "object_id" ] }, "AffiliateFirm": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string", "readOnly": true }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 }, "contact_name": { "type": "string", "maxLength": 75 }, "contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "is_338_firm": { "type": "boolean", "readOnly": true } }, "required": [ "address", "crd", "is_338_firm", "name", "object_id" ] }, "Attachment": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "name", "object_id" ] }, "AttachmentRequest": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name", "object_id" ] }, "AumTier": { "type": "object", "properties": { "aum_limit": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "aum_fee": { "type": "string", "format": "decimal", "description": "Fee as a decimal (e.g. 0.0100 = 1% = 100 bps). To convert from bps, divide by 10,000." } } }, "Beneficiary": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] }, "BeneficiaryManyPossible": { "oneOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] }, { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } ] }, "BeneficiaryManyPossibleRequest": { "oneOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] }, { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } ] }, "BeneficiaryRequest": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] }, "BrokerDealer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 75 }, "address": { "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" ] }, "contact_name": { "type": "string", "maxLength": 75 } }, "required": [ "address" ] }, "Company": { "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\n* `SETUP_COMPLETE` - Setup Complete", "x-spec-enum-id": "2697e66770f4bfe2", "readOnly": true } }, "required": [ "name", "object_id", "status" ] }, "CompanyAffiliates": { "type": "object", "properties": { "broker_dealer": { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 75 }, "address": { "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" ] }, "contact_name": { "type": "string", "maxLength": 75 } }, "required": [ "address" ] } ], "nullable": true }, "advisor": { "allOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string" }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "address", "crd", "name", "object_id" ] } ], "nullable": true }, "advisor_firm": { "allOf": [ { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string", "readOnly": true }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 }, "contact_name": { "type": "string", "maxLength": 75 }, "contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "is_338_firm": { "type": "boolean", "readOnly": true } }, "required": [ "address", "crd", "is_338_firm", "name", "object_id" ] } ], "nullable": true } }, "required": [ "advisor", "advisor_firm", "broker_dealer" ] }, "DeferralElection": { "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" ] }, "DeferralElectionRequest": { "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" ] }, "Deferrals": { "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", "nullable": true, "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" ] }, "DeferralsRequest": { "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" ] } } }, "Disbursement": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "Unique identifier for the disbursement." }, "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "status": { "type": "string", "readOnly": true, "description": "The current status of the disbursement (e.g., Pending Approval, Funds Sent, etc.)" }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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" ] } ], "description": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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" ] } ], "description": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "description": "The participant's name" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "description": "The participant's phone number" }, "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" ] } ], "nullable": true, "description": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "object_id", "payment_method", "phone", "reason", "status" ] }, "DisbursementInfo": { "type": "object", "description": "Provides information about available disbursement options before creating a disbursement.", "properties": { "available_reasons": { "type": "array", "items": { "type": "string" }, "description": "List of available disbursement reasons for this participant." }, "missing_reasons": { "type": "object", "additionalProperties": {}, "description": "Dictionary of unavailable reasons with explanations why." }, "pretax_available": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Available pre-tax balance for disbursement." }, "posttax_available": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Available post-tax balance for disbursement." }, "minimum_disbursement": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Minimum allowed disbursement amount." } }, "required": [ "available_reasons", "minimum_disbursement", "missing_reasons", "posttax_available", "pretax_available" ] }, "DisbursementRequest": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "hardship_proof_document": { "type": "string", "format": "byte", "description": "Base64-encoded proof document required for hardship disbursements and death disbursements.", "writeOnly": true }, "hardship_signature": { "type": "string", "format": "byte", "description": "Base64-encoded signature image for hardship disbursements. Recommended dimensions: 500px width x 150px height (10:3 aspect ratio) to match the final document format.", "writeOnly": true }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "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": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "payment_method", "phone", "reason" ] }, "DocumentList": { "type": "object", "description": "Serializer for listing available documents for a participant.", "properties": { "available_documents": { "type": "array", "items": { "enum": [ "plan_document", "plan_highlights", "fee_disclosures", "qdia", "safe_harbor_notice", "auto_enroll_notice" ], "type": "string", "description": "* `plan_document` - plan_document\n* `plan_highlights` - plan_highlights\n* `fee_disclosures` - fee_disclosures\n* `qdia` - qdia\n* `safe_harbor_notice` - safe_harbor_notice\n* `auto_enroll_notice` - auto_enroll_notice", "x-spec-enum-id": "9778ac1b6a16c5cc" } } }, "required": [ "available_documents" ] }, "DocumentSignedUrl": { "type": "object", "description": "Serializer for document signed URLs.", "properties": { "signed_url": { "type": "string", "format": "uri" } }, "required": [ "signed_url" ] }, "DollarPerHeadTier": { "type": "object", "properties": { "participant_limit": { "type": "integer" }, "dollar_per_head": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "participant_limit" ] }, "Events": { "type": "object", "description": "Serializer for participant events.\n\nUsed to get and set event types for a participant. The event types are defined in the ParticipantEvent model.", "properties": { "event_types": { "type": "array", "items": { "enum": [ "Completed Setup", "eDocument Agreement", "Viewed Documents", "Skipped Guided Portfolio", "Remove eDocument Agreement", "Opt Out" ], "type": "string", "description": "* `Completed Setup` - Completed Setup\n* `eDocument Agreement` - eDocument Agreement\n* `Viewed Documents` - Viewed Documents\n* `Skipped Guided Portfolio` - Skipped Guided Portfolio\n* `Remove eDocument Agreement` - Remove eDocument Agreement\n* `Opt Out` - Opt Out", "x-spec-enum-id": "00d31436ce65e13d" }, "minItems": 1 } }, "required": [ "event_types" ] }, "EventsRequest": { "type": "object", "description": "Serializer for participant events.\n\nUsed to get and set event types for a participant. The event types are defined in the ParticipantEvent model.", "properties": { "event_types": { "type": "array", "items": { "enum": [ "Completed Setup", "eDocument Agreement", "Viewed Documents", "Skipped Guided Portfolio", "Remove eDocument Agreement", "Opt Out" ], "type": "string", "description": "* `Completed Setup` - Completed Setup\n* `eDocument Agreement` - eDocument Agreement\n* `Viewed Documents` - Viewed Documents\n* `Skipped Guided Portfolio` - Skipped Guided Portfolio\n* `Remove eDocument Agreement` - Remove eDocument Agreement\n* `Opt Out` - Opt Out", "x-spec-enum-id": "00d31436ce65e13d" }, "minItems": 1 } }, "required": [ "event_types" ] }, "Firm338Investment": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "description": "This short 250 char description will be shown on the 'Select Fund Lineup' page of the company questions section of plan setup. If there are fees for this lineup, they should be listed here.", "maxLength": 250 }, "custodian": { "type": "string", "enum": [ "Matrix", "Drive Wealth", "Apex", "Matrix And Drive Wealth", "Matrix And Apex", "Drive Wealth And Apex", "Matrix And Drive Wealth And Apex" ] }, "investments": { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] }, "readOnly": true } }, "required": [ "custodian", "investments", "object_id" ] }, "IndividualMovement": { "type": "object", "properties": { "object_id": { "type": "string" }, "memo": { "type": "string", "maxLength": 200 }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,12}(?:\\.\\d{0,8})?$" }, "movement_type": { "enum": [ "Employee Deferral", "Non-roth After Tax Deferral", "Rollover", "Dividend", "Discretionary Non Elective (Profit Sharing)", "Safe Harbor Non Elective", "Discretionary Match", "Safe Harbor Match", "Correction Contribution (QMAC)", "Qualified Non-Elective Contribution", "Loan Interest", "Disbursement", "Correction Disbursement", "Lost Earnings Contribution", "Transferred Earnings", "Loan", "Fee", "Other" ], "type": "string", "description": "* `Employee Deferral` - Employee Deferral\n* `Non-roth After Tax Deferral` - Non-roth After Tax Deferral\n* `Rollover` - Rollover\n* `Dividend` - Dividend\n* `Discretionary Non Elective (Profit Sharing)` - Discretionary Non Elective (Profit Sharing)\n* `Safe Harbor Non Elective` - Safe Harbor Non Elective\n* `Discretionary Match` - Discretionary Match\n* `Safe Harbor Match` - Safe Harbor Match\n* `Correction Contribution (QMAC)` - Correction Contribution (QMAC)\n* `Qualified Non-Elective Contribution` - Qualified Non-Elective Contribution\n* `Loan Interest` - Loan Interest\n* `Disbursement` - Disbursement\n* `Correction Disbursement` - Correction Disbursement\n* `Lost Earnings Contribution` - Lost Earnings Contribution\n* `Transferred Earnings` - Transferred Earnings\n* `Loan` - Loan\n* `Fee` - Fee\n* `Other` - Other", "x-spec-enum-id": "c7efb0d4aff775fd" }, "applied_date": { "type": "string", "format": "date", "nullable": true }, "account_type": { "enum": [ "Pre-tax", "Post-tax", "Vested Contribution", "Non-vested Contribution" ], "type": "string", "description": "* `Pre-tax` - Pre-tax\n* `Post-tax` - Post-tax\n* `Vested Contribution` - Vested Contribution\n* `Non-vested Contribution` - Non-vested Contribution", "x-spec-enum-id": "5548afd0b1c14da0" }, "tax_type": { "enum": [ "Pre-tax", "Post-tax" ], "type": "string", "description": "* `Pre-tax` - Pre-tax\n* `Post-tax` - Post-tax", "x-spec-enum-id": "40e39026ee7fdc9a" }, "testing_exempt": { "type": "boolean" } }, "required": [ "account_type", "movement_type", "object_id" ] }, "Investment": { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] }, "InvestmentHistory": { "type": "object", "description": "Investment information for a single day in portfolio history.", "properties": { "object_id": { "type": "string", "description": "The object_id of the associated Investment" }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,3})?$" }, "share_price": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,9})?$" }, "basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "proceeds": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "basis", "object_id", "proceeds", "share_price", "shares" ] }, "InvestmentTransaction": { "type": "object", "properties": { "object_id": { "type": "string" }, "investment": { "allOf": [ { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } ], "readOnly": true }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,4})?$" }, "share_price": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,9})?$" }, "amount_paid": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,14}(?:\\.\\d{0,2})?$" }, "settle_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "readOnly": true }, "money_sources": { "type": "array", "items": { "type": "object", "properties": { "money_source": { "type": "string", "enum": [ "Employee Deferral", "Discretionary Non Elective (Profit Sharing)", "Safe Harbor Non Elective", "Discretionary Match", "Safe Harbor Match", "Correction Contribution (QMAC)", "Qualified Non-Elective Contribution", "Rollover", "Other", "Individual Contribution", "Conversion" ] }, "tax_type": { "type": "string", "enum": [ "Pre-tax", "Post-tax" ] }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,9})?$" } }, "required": [ "money_source", "shares", "tax_type" ] }, "readOnly": true } }, "required": [ "amount_paid", "investment", "money_sources", "object_id", "share_price", "shares", "status" ] }, "InvestmentTransactionMoneySource": { "type": "object", "properties": { "money_source": { "type": "string", "enum": [ "Employee Deferral", "Discretionary Non Elective (Profit Sharing)", "Safe Harbor Non Elective", "Discretionary Match", "Safe Harbor Match", "Correction Contribution (QMAC)", "Qualified Non-Elective Contribution", "Rollover", "Other", "Individual Contribution", "Conversion" ] }, "tax_type": { "type": "string", "enum": [ "Pre-tax", "Post-tax" ] }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,9})?$" } }, "required": [ "money_source", "shares", "tax_type" ] }, "Loan": { "type": "object", "description": "Represents a due loan payment", "properties": { "todays_payment": { "type": "string", "readOnly": true } }, "required": [ "todays_payment" ] }, "LoanBalance": { "type": "object", "properties": { "loan_balance": { "type": "number", "format": "double", "readOnly": true }, "issue_date": { "type": "string", "format": "date" }, "first_payment_date": { "type": "string", "format": "date", "nullable": true }, "years_duration": { "type": "integer", "readOnly": true } }, "required": [ "first_payment_date", "issue_date", "loan_balance", "years_duration" ] }, "LoanRequest": { "type": "object", "description": "A loan request for a participant.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "description": "Not required if is_primary_residence is true", "maxLength": 200, "minLength": 5 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer" }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "date": { "type": "string", "readOnly": true }, "interest_rate": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,10})?$", "readOnly": true }, "balance": { "type": "string", "readOnly": true }, "period_payment": { "type": "string", "readOnly": true }, "promissory_note_url": { "type": "string", "readOnly": true }, "fee_amount": { "type": "string", "readOnly": true }, "wire_transfer_fee": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "Active", "Reamortized", "Closed", "Past Due", "In Default", "Deemed Distribution", "Not Complete", "Requested", "Approved", "Canceled", "Denied", "Needs Amortization Approval" ], "readOnly": true, "description": "A signature is still required if not \"Requested\"" } }, "required": [ "address", "balance", "date", "dob", "fee_amount", "interest_rate", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "object_id", "payment_method", "period_payment", "phone", "promissory_note_url", "status", "wire_transfer_fee" ] }, "LoanRequestInfo": { "type": "object", "properties": { "can_take_loan": { "type": "boolean" }, "cannot_take_reason": { "type": "string", "nullable": true }, "fee_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "wire_transfer_fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "available_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "available_amount", "can_take_loan", "cannot_take_reason", "fee_amount", "wire_transfer_fee" ] }, "LoanRequestRequest": { "type": "object", "description": "A loan request for a participant.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "minLength": 5, "description": "Not required if is_primary_residence is true", "maxLength": 200 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer", "minimum": 1 }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "minLength": 1, "description": "Only used if payment_method is not \"Check\"" } }, "required": [ "address", "dob", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "payment_method", "phone" ] }, "LoanSignatureSubmission": { "type": "object", "description": "Submit a signature for a loan request.", "properties": { "promissory_note_url": { "type": "string", "readOnly": true } }, "required": [ "promissory_note_url" ] }, "LoanSignatureSubmissionRequest": { "type": "object", "description": "Submit a signature for a loan request.", "properties": { "signature": { "type": "string", "format": "byte", "description": "Base64-encoded image data", "writeOnly": true } }, "required": [ "signature" ] }, "NonElectivePercentage": { "type": "object", "properties": { "contribution_rate": { "type": "integer" } }, "required": [ "contribution_rate" ] }, "OtherPayrollLineAdditions": { "type": "object", "description": "Additional payroll deductions not covered by employee contributions to 401k or company matches.\n\nCurrently, 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\n* `Loan Interest` - Loan Interest", "x-spec-enum-id": "a05082d953d3615e" } }, "required": [ "additional_amount", "other_type" ] }, "OtherPayrollLineAdditionsRequest": { "type": "object", "description": "Additional payroll deductions not covered by employee contributions to 401k or company matches.\n\nCurrently, 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\n* `Loan Interest` - Loan Interest", "x-spec-enum-id": "a05082d953d3615e" } }, "required": [ "additional_amount", "other_type" ] }, "PaginatedAffiliateFirmList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string", "readOnly": true }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 }, "contact_name": { "type": "string", "maxLength": 75 }, "contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "is_338_firm": { "type": "boolean", "readOnly": true } }, "required": [ "address", "crd", "is_338_firm", "name", "object_id" ] } } } }, "PaginatedAffiliateList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "crd": { "type": "string" }, "address": { "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" ] }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "address", "crd", "name", "object_id" ] } } } }, "PaginatedBeneficiaryList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } }, "required": [ "dob", "name", "percentage" ] } } } }, "PaginatedCompanyList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "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\n* `SETUP_COMPLETE` - Setup Complete", "x-spec-enum-id": "2697e66770f4bfe2", "readOnly": true } }, "required": [ "name", "object_id", "status" ] } } } }, "PaginatedDisbursementList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "Convert chosen empty strings into None during serialization. Specify with the `empty_to_null_fields` Meta attribute.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "Unique identifier for the disbursement." }, "reason": { "type": "string", "enum": [ "Termination of Employment", "Hardship Withdrawal", "Pre-Retirement Withdrawal", "Qualified Domestic Relations Order", "Retirement Age Withdrawal", "Required Minimum Distribution", "Permanent Disability", "Death of Participant", "Plan Termination", "IRA", "Emergency Expense", "Correction", "Move Rollover Funds", "Permissible Withdrawal" ], "description": "The reason for the disbursement request." }, "pretax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Pre-tax amount to disburse." }, "posttax_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Post-tax amount to disburse." }, "pretax_memo": { "type": "string", "description": "Payment memo for pre-tax disbursement (max 20 characters). Required when pretax_amount is provided.", "maxLength": 20 }, "posttax_memo": { "type": "string", "description": "Payment memo for post-tax disbursement (max 20 characters). Required when posttax_amount is provided.", "maxLength": 20 }, "posttax_payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "Payment method for post-tax portion (if different from pre-tax). Only used in split disbursements when different from payment_method." }, "posttax_bank_name": { "type": "string", "description": "Bank name for post-tax portion. Only used in split disbursements when different from payment_method." }, "posttax_bank_routing_aba_number": { "type": "string", "description": "Routing number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_bank_account_number": { "type": "string", "description": "Account number for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "posttax_name_on_bank_account": { "type": "string", "description": "Account holder for post-tax portion. Only used in split disbursements when different from payment_method. Not necessary for Check Payments." }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer", "Fee Transfer", "Forced Rollover" ], "description": "The payment method to use (e.g., Check, ACH, Wire). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion." }, "status": { "type": "string", "readOnly": true, "description": "The current status of the disbursement (e.g., Pending Approval, Funds Sent, etc.)" }, "is_rollover": { "type": "boolean", "default": false, "description": "Set to true if this is a rollover to a new provider." }, "payment_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" ] } ], "description": "Payment address for pre-tax portion (defaults to participant's address if not provided). Only required if different from participant's address." }, "posttax_payment_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" ] } ], "description": "Payment address for post-tax portion (defaults to participant's address if not provided)." }, "bank_name": { "type": "string", "description": "Name of the bank for ACH/Wire payments (used for pre-tax portion in splits). For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion" }, "bank_routing_aba_number": { "type": "string", "description": "Routing (ABA) number for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "bank_account_number": { "type": "string", "description": "Bank account number for payment. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "name_on_bank_account": { "type": "string", "description": "Name of the account holder for the bank account. For single disbursements, use this field regardless of tax type. For split disbursements, this applies to the pre-tax portion. Not necessary for Check Payments." }, "federal_withholding_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Federal tax withholding percent (required for Hardship and RMD disbursements). Enter as percentage (e.g., 10.0 for 10%)" }, "hardship": { "type": "string", "enum": [ "Expenses for Medical Care", "Purchase of a Principal Residence", "Educational Fees", "Prevent Eviction or Foreclosure", "Funeral Expenses", "Repair Damage to Principal Residence", "Qualified Federally Declared Disasters" ], "description": "Specific hardship reason (required for hardship disbursements)." }, "name": { "type": "string", "description": "The participant's name" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "phone": { "type": "string", "description": "The participant's phone number" }, "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" ] } ], "nullable": true, "description": "The participant's address" } }, "required": [ "address", "dob", "married", "name", "object_id", "payment_method", "phone", "reason", "status" ] } } } }, "PaginatedFirm338InvestmentList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "nullable": true, "maxLength": 100 }, "description": { "type": "string", "description": "This short 250 char description will be shown on the 'Select Fund Lineup' page of the company questions section of plan setup. If there are fees for this lineup, they should be listed here.", "maxLength": 250 }, "custodian": { "type": "string", "enum": [ "Matrix", "Drive Wealth", "Apex", "Matrix And Drive Wealth", "Matrix And Apex", "Drive Wealth And Apex", "Matrix And Drive Wealth And Apex" ] }, "investments": { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] }, "readOnly": true } }, "required": [ "custodian", "investments", "object_id" ] } } } }, "PaginatedIndividualMovementList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "memo": { "type": "string", "maxLength": 200 }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,12}(?:\\.\\d{0,8})?$" }, "movement_type": { "enum": [ "Employee Deferral", "Non-roth After Tax Deferral", "Rollover", "Dividend", "Discretionary Non Elective (Profit Sharing)", "Safe Harbor Non Elective", "Discretionary Match", "Safe Harbor Match", "Correction Contribution (QMAC)", "Qualified Non-Elective Contribution", "Loan Interest", "Disbursement", "Correction Disbursement", "Lost Earnings Contribution", "Transferred Earnings", "Loan", "Fee", "Other" ], "type": "string", "description": "* `Employee Deferral` - Employee Deferral\n* `Non-roth After Tax Deferral` - Non-roth After Tax Deferral\n* `Rollover` - Rollover\n* `Dividend` - Dividend\n* `Discretionary Non Elective (Profit Sharing)` - Discretionary Non Elective (Profit Sharing)\n* `Safe Harbor Non Elective` - Safe Harbor Non Elective\n* `Discretionary Match` - Discretionary Match\n* `Safe Harbor Match` - Safe Harbor Match\n* `Correction Contribution (QMAC)` - Correction Contribution (QMAC)\n* `Qualified Non-Elective Contribution` - Qualified Non-Elective Contribution\n* `Loan Interest` - Loan Interest\n* `Disbursement` - Disbursement\n* `Correction Disbursement` - Correction Disbursement\n* `Lost Earnings Contribution` - Lost Earnings Contribution\n* `Transferred Earnings` - Transferred Earnings\n* `Loan` - Loan\n* `Fee` - Fee\n* `Other` - Other", "x-spec-enum-id": "c7efb0d4aff775fd" }, "applied_date": { "type": "string", "format": "date", "nullable": true }, "account_type": { "enum": [ "Pre-tax", "Post-tax", "Vested Contribution", "Non-vested Contribution" ], "type": "string", "description": "* `Pre-tax` - Pre-tax\n* `Post-tax` - Post-tax\n* `Vested Contribution` - Vested Contribution\n* `Non-vested Contribution` - Non-vested Contribution", "x-spec-enum-id": "5548afd0b1c14da0" }, "tax_type": { "enum": [ "Pre-tax", "Post-tax" ], "type": "string", "description": "* `Pre-tax` - Pre-tax\n* `Post-tax` - Post-tax", "x-spec-enum-id": "40e39026ee7fdc9a" }, "testing_exempt": { "type": "boolean" } }, "required": [ "account_type", "movement_type", "object_id" ] } } } }, "PaginatedInvestmentList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } } } }, "PaginatedInvestmentTransactionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "investment": { "allOf": [ { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } ], "readOnly": true }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,4})?$" }, "share_price": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,9})?$" }, "amount_paid": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,14}(?:\\.\\d{0,2})?$" }, "settle_date": { "type": "string", "format": "date", "nullable": true }, "status": { "type": "string", "readOnly": true }, "money_sources": { "type": "array", "items": { "type": "object", "properties": { "money_source": { "type": "string", "enum": [ "Employee Deferral", "Discretionary Non Elective (Profit Sharing)", "Safe Harbor Non Elective", "Discretionary Match", "Safe Harbor Match", "Correction Contribution (QMAC)", "Qualified Non-Elective Contribution", "Rollover", "Other", "Individual Contribution", "Conversion" ] }, "tax_type": { "type": "string", "enum": [ "Pre-tax", "Post-tax" ] }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,9})?$" } }, "required": [ "money_source", "shares", "tax_type" ] }, "readOnly": true } }, "required": [ "amount_paid", "investment", "money_sources", "object_id", "share_price", "shares", "status" ] } } } }, "PaginatedLoanRequestList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "A loan request for a participant.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "is_primary_residence": { "type": "boolean" }, "loan_reason": { "type": "string", "description": "Not required if is_primary_residence is true", "maxLength": 200, "minLength": 5 }, "loan_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "loan_duration": { "type": "integer" }, "payment_method": { "type": "string", "enum": [ "Check", "Wire", "ACH Transfer" ] }, "account_holder": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "bank_name": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "account_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "routing_number": { "type": "string", "description": "Only used if payment_method is not \"Check\"" }, "date": { "type": "string", "readOnly": true }, "interest_rate": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,10})?$", "readOnly": true }, "balance": { "type": "string", "readOnly": true }, "period_payment": { "type": "string", "readOnly": true }, "promissory_note_url": { "type": "string", "readOnly": true }, "fee_amount": { "type": "string", "readOnly": true }, "wire_transfer_fee": { "type": "string", "readOnly": true }, "status": { "type": "string", "enum": [ "Active", "Reamortized", "Closed", "Past Due", "In Default", "Deemed Distribution", "Not Complete", "Requested", "Approved", "Canceled", "Denied", "Needs Amortization Approval" ], "readOnly": true, "description": "A signature is still required if not \"Requested\"" } }, "required": [ "address", "balance", "date", "dob", "fee_amount", "interest_rate", "is_primary_residence", "loan_amount", "loan_duration", "married", "name", "object_id", "payment_method", "period_payment", "phone", "promissory_note_url", "status", "wire_transfer_fee" ] } } } }, "PaginatedParticipantList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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" ] } } } }, "PaginatedParticipantNotificationList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "subject": { "type": "string", "readOnly": true }, "notification_content": { "type": "string", "readOnly": true }, "content_is_html": { "type": "boolean", "readOnly": true }, "status": { "type": "string", "enum": [ "New", "Viewed", "Archived" ] }, "timestamp": { "type": "string", "format": "date-time", "readOnly": true }, "attachment": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "name", "object_id" ] }, "readOnly": true }, "signed_url": { "type": "string", "description": "Get signed URL for attachments if needed.", "readOnly": true } }, "required": [ "attachment", "content_is_html", "notification_content", "object_id", "signed_url", "status", "subject", "timestamp" ] } } } }, "PaginatedParticipantRolloverList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "Incomplete", "Submitted", "Funds Received", "Abandoned" ], "readOnly": true }, "rollover_acceptance_letter_url": { "type": "string", "readOnly": true } }, "required": [ "address", "dob", "married", "name", "object_id", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "rollover_acceptance_letter_url", "status", "total_rollover_amount" ] } } } }, "PaginatedPartnerPricingTierList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "tier_name": { "type": "string", "maxLength": 100 }, "aum_tiers_banded": { "type": "boolean" }, "aum_tiers": { "type": "array", "items": { "type": "object", "properties": { "aum_limit": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "aum_fee": { "type": "string", "format": "decimal", "description": "Fee as a decimal (e.g. 0.0100 = 1% = 100 bps). To convert from bps, divide by 10,000." } } }, "readOnly": true }, "per_head_tiers": { "type": "array", "items": { "type": "object", "properties": { "participant_limit": { "type": "integer" }, "dollar_per_head": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "participant_limit" ] }, "readOnly": true }, "other_fees": { "type": "array", "items": { "type": "object", "properties": { "fee_frequency": { "type": "string", "enum": [ "One-Time", "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly", "Quarterly", "Semi-Annually", "Yearly" ] }, "fee_description": { "type": "string" }, "fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "fee_description", "fee_frequency" ] }, "readOnly": true } }, "required": [ "aum_tiers", "aum_tiers_banded", "object_id", "other_fees", "per_head_tiers" ] } } } }, "PaginatedPayrollLineList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "A payroll line represents payroll for one participant and has the associated id of that participant.\n\nIt 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.\n\nCurrently, 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\n* `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" ] } } } }, "PaginatedPooledPlanList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 }, "effective_date": { "type": "string", "format": "date", "nullable": true }, "terminated_date": { "type": "string", "format": "date", "nullable": true }, "status": { "enum": [ "DRAFT", "ACTIVE", "INACTIVE" ], "type": "string", "description": "* `DRAFT` - DRAFT\n* `ACTIVE` - ACTIVE\n* `INACTIVE` - INACTIVE", "x-spec-enum-id": "8b036d93c4c21fd8" }, "matrix_alliance_code": { "type": "string", "maxLength": 16 } }, "required": [ "name", "object_id" ] } } } }, "PaginatedPortfolioHistoryList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "description": "Portfolio information for a single day.", "properties": { "investments": { "type": "array", "items": { "type": "object", "description": "Investment information for a single day in portfolio history.", "properties": { "object_id": { "type": "string", "description": "The object_id of the associated Investment" }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,3})?$" }, "share_price": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,9})?$" }, "basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "proceeds": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "basis", "object_id", "proceeds", "share_price", "shares" ] } }, "date": { "type": "string", "format": "date" }, "cash": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "cash", "date", "investments" ] } } } }, "PaginatedPortfolioInvestmentList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "type": "object", "properties": { "percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "investment": { "allOf": [ { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } ], "readOnly": true }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "value": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "status": { "enum": [ "PENDING_SALE", "ACTIVE" ], "type": "string", "description": "* `PENDING_SALE` - Pending Sale\n* `ACTIVE` - Active", "x-spec-enum-id": "a442a24a44038e9a", "readOnly": true } }, "required": [ "investment", "percent", "shares", "status", "value" ] } } } }, "Participant": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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" ] }, "ParticipantNotification": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "subject": { "type": "string", "readOnly": true }, "notification_content": { "type": "string", "readOnly": true }, "content_is_html": { "type": "boolean", "readOnly": true }, "status": { "type": "string", "enum": [ "New", "Viewed", "Archived" ] }, "timestamp": { "type": "string", "format": "date-time", "readOnly": true }, "attachment": { "type": "array", "items": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "name", "object_id" ] }, "readOnly": true }, "signed_url": { "type": "string", "description": "Get signed URL for attachments if needed.", "readOnly": true } }, "required": [ "attachment", "content_is_html", "notification_content", "object_id", "signed_url", "status", "subject", "timestamp" ] }, "ParticipantOrList": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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" ] }, { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "met_eligibility_date": { "type": "string", "format": "date", "readOnly": true, "nullable": true }, "met_match_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "met_profit_share_eligibility_date": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "ssn": { "type": "string", "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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", "nullable": true, "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" ] } ], "nullable": true }, "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" ] } } ] }, "ParticipantOrListRequest": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "required": [ "ssn", "start_date" ] } } ] }, "ParticipantRequest": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } }, "required": [ "ssn", "start_date" ] }, "ParticipantRollover": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "object_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The participant's name" }, "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" ] } ], "nullable": true, "description": "The participant's address" }, "phone": { "type": "string", "description": "The participant's phone number" }, "dob": { "type": "string", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "Incomplete", "Submitted", "Funds Received", "Abandoned" ], "readOnly": true }, "rollover_acceptance_letter_url": { "type": "string", "readOnly": true } }, "required": [ "address", "dob", "married", "name", "object_id", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "rollover_acceptance_letter_url", "status", "total_rollover_amount" ] }, "ParticipantRolloverRequest": { "type": "object", "description": "A rollover request for a participant that accepts all information in a single request.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The participant's name" }, "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": "The participant's address" }, "phone": { "type": "string", "minLength": 1, "description": "The participant's phone number" }, "dob": { "type": "string", "format": "date", "description": "The participant's date of birth" }, "married": { "type": "boolean", "description": "The participant's marital status" }, "prior_plan_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_name": { "type": "string", "minLength": 1, "maxLength": 250 }, "prior_tpa_contact_phone": { "type": "string", "minLength": 1, "maxLength": 40 }, "prior_tpa_contact_email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 }, "prior_plan_type": { "type": "string", "enum": [ "Traditional (pre-tax) 401(k)", "Roth (post-tax) 401(k)", "Mixed Traditional/Roth 401(k)", "Traditional (pre-tax) IRA", "Roth (post-tax) IRA", "Mixed Traditional/Roth IRA", "Simple IRA", "SEP IRA", "Conduit IRA", "403(a)", "403(b)", "Profit Sharing Plan", "Defined Benefit Plan", "Money Purchase Plan", "Governmental 457", "Roth (post-tax) Governmental 457", "Pre-tax Qualified Retirement Plan", "Post-tax Qualified Retirement Plan" ] }, "total_rollover_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "roth_contribution_basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$", "default": "0.00" }, "roth_contribution_first_year": { "type": "integer", "minimum": 0, "default": 0 }, "is_minimum_required_distribution": { "type": "boolean", "default": false }, "is_hardship_withdrawal": { "type": "boolean", "default": false }, "is_indirect_rollover": { "type": "boolean", "default": false } }, "required": [ "address", "dob", "married", "name", "phone", "prior_plan_name", "prior_plan_type", "prior_tpa_contact_email", "prior_tpa_contact_name", "prior_tpa_contact_phone", "total_rollover_amount" ] }, "ParticipantSetup": { "type": "object", "description": "Serializer for participant setup information including plan details and deferral status.", "properties": { "eligibility_date": { "type": "string", "format": "date" }, "has_deferrals": { "type": "boolean" }, "plan_name": { "type": "string" }, "plan_type": { "type": "string" }, "plan_number": { "type": "integer" }, "plan_allow_self_direct": { "type": "boolean" }, "opted_to_self_direct": { "type": "boolean" }, "auto_enroll_percent": { "type": "string", "nullable": true, "default": "5", "maxLength": 2 }, "has_eDocs_agreement": { "type": "boolean" } }, "required": [ "eligibility_date", "has_deferrals", "has_eDocs_agreement", "opted_to_self_direct", "plan_allow_self_direct", "plan_name", "plan_number", "plan_type" ] }, "PartnerPricingFrequency": { "type": "object", "properties": { "fee_frequency": { "type": "string", "enum": [ "One-Time", "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly", "Quarterly", "Semi-Annually", "Yearly" ] }, "fee_description": { "type": "string" }, "fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "fee_description", "fee_frequency" ] }, "PartnerPricingTier": { "type": "object", "properties": { "object_id": { "type": "string", "readOnly": true }, "tier_name": { "type": "string", "maxLength": 100 }, "aum_tiers_banded": { "type": "boolean" }, "aum_tiers": { "type": "array", "items": { "type": "object", "properties": { "aum_limit": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "aum_fee": { "type": "string", "format": "decimal", "description": "Fee as a decimal (e.g. 0.0100 = 1% = 100 bps). To convert from bps, divide by 10,000." } } }, "readOnly": true }, "per_head_tiers": { "type": "array", "items": { "type": "object", "properties": { "participant_limit": { "type": "integer" }, "dollar_per_head": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "participant_limit" ] }, "readOnly": true }, "other_fees": { "type": "array", "items": { "type": "object", "properties": { "fee_frequency": { "type": "string", "enum": [ "One-Time", "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly", "Quarterly", "Semi-Annually", "Yearly" ] }, "fee_description": { "type": "string" }, "fee": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" } }, "required": [ "fee_description", "fee_frequency" ] }, "readOnly": true } }, "required": [ "aum_tiers", "aum_tiers_banded", "object_id", "other_fees", "per_head_tiers" ] }, "PatchedBeneficiaryRequest": { "type": "object", "properties": { "object_id": { "type": "string", "nullable": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "dob": { "type": "string", "format": "date", "title": "Birthday" }, "percentage": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,0})?$", "description": "Enter a percentage, so 1% would be 1.0 and 5 bps would be 0.05" } } }, "PatchedParticipantNotificationRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "New", "Viewed", "Archived" ] } } }, "PatchedParticipantRequest": { "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\nis eligible to contribute. In addition, for ineligible participants, the deferrals will always have a 0 amount.\nWhen creating a participant, either phone or email are required (preferably both). When updating a participant, object_id is required.\nIf a 'termination_date' has previously been set, pushing a 'start_date' after it will rehire this participant.", "properties": { "object_id": { "type": "string", "nullable": true }, "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", "format": "date", "nullable": true }, "ssn": { "type": "string", "minLength": 1, "title": "Social Security Number", "maxLength": 9 }, "dob": { "type": "string", "format": "date", "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true }, "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" ] } ], "nullable": true } } }, "PayrollFile": { "type": "object", "description": "A Payroll File is a single payroll for a company with many pay lines, one for each participant.\n\nThere are a couple dates that can be provided for a payroll file, but check_date is the only required one.\nis_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", "format": "date", "nullable": true }, "pay_period_end": { "type": "string", "format": "date", "nullable": true }, "check_date": { "type": "string", "format": "date", "title": "Check/Pay Date (W2 date)" }, "ach_date": { "type": "string", "format": "date", "readOnly": true, "nullable": 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.\n\nIt 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.\n\nCurrently, 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\n* `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" ] }, "PayrollFileRequest": { "type": "object", "description": "A Payroll File is a single payroll for a company with many pay lines, one for each participant.\n\nThere are a couple dates that can be provided for a payroll file, but check_date is the only required one.\nis_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", "format": "date", "nullable": true }, "pay_period_end": { "type": "string", "format": "date", "nullable": true }, "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.\n\nIt 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.\n\nCurrently, 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\n* `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" ] }, "PayrollLine": { "type": "object", "description": "A payroll line represents payroll for one participant and has the associated id of that participant.\n\nIt 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.\n\nCurrently, 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\n* `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" ] }, "PayrollLineRequest": { "type": "object", "description": "A payroll line represents payroll for one participant and has the associated id of that participant.\n\nIt 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.\n\nCurrently, 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\n* `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" ] }, "PlanContribution": { "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" ] } ], "nullable": true }, "nondiscretionary_nonelective": { "allOf": [ { "type": "object", "properties": { "contribution_rate": { "type": "integer" } }, "required": [ "contribution_rate" ] } ], "nullable": true } }, "required": [ "discretionary_matches", "discretionary_nonelective", "nondiscretionary_nonelective", "plan_matches" ] }, "PlanMatchPercentage": { "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" ] }, "PlanMatchPercentageRequest": { "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" ] }, "PlanProvisions": { "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", "description": "Return the auto increase percentage.\nReturns null if force_auto_deferral_increase is False or the plan is a QACA plan.\nOtherwise, returns 1 (default value).", "readOnly": true, "nullable": true }, "auto_increase_cap": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" ], "nullable": true, "description": "Maximum percentage that auto-enrollment can increase to." }, "plan_effective_date": { "type": "string", "format": "date", "nullable": true }, "plan_restatement_date": { "type": "string", "format": "date", "nullable": true }, "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", "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" ], "nullable": true, "description": "Specifies when participants become eligible for employer matching, if different from regular eligibility" }, "profit_share_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" ], "nullable": true, "description": "Specifies when participants become eligible for profit sharing, if different from regular eligibility" }, "hours_of_service": { "type": "integer", "description": "Returns the hours of service requirement.\nReturns null if eligibility_delay is not 'Hours of Service'.", "readOnly": true, "nullable": 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", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "nullable": true, "description": "Only used if different from the regular entry date" }, "profit_share_entry_date": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "nullable": true, "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", "maximum": 65535, "minimum": 0, "nullable": true, "description": "Only fill this in if it's different from the regular min age." }, "profit_share_minimum_age": { "type": "integer", "maximum": 65535, "minimum": 0, "nullable": true, "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", "format": "date", "description": "Returns the plan cancellation date.\nReturns null if there is no cancellation or if there's an error retrieving the date.", "readOnly": true, "nullable": 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" ] }, "PlanSetup": { "type": "object", "description": "Serializer for plan provisions and settings. Creates both a company and a plan on POST.", "properties": { "object_id": { "type": "string", "readOnly": true, "description": "ID for the created or updated company. Use this as the path parameter for subsequent PUT requests to update the plan." }, "company_name": { "type": "string", "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", "description": "Email address of the company's primary contact.", "maxLength": 254 }, "primary_contact_name": { "type": "string", "description": "Full name of the company's primary contact.", "maxLength": 75 }, "ein": { "type": "string", "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", "description": "Full name of the plan trustee.", "maxLength": 250 }, "trustee_email": { "type": "string", "format": "email", "description": "Email address of the plan trustee.", "maxLength": 250 }, "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" ] } ], "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", "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "object_id", "primary_contact_email", "primary_contact_name" ] }, "PlanSetupRequest": { "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", "Firehouse Payroll", "G&A Partners, LLC", "Global Wages Inc", "GoCo", "Green Payroll", "Greenlink Payroll", "GTM Payroll Services Evolution", "GTM Payroll Services isolved", "Gusto", "Helpide - PrismHR", "HigherUp HCM", "Highflyer HR", "Hire Level Payroll", "HireAthena", "HRtoGO", "Hubstaff", "Human Elements", "IBusiness Solutions", "Ideal Payroll isolved", "Infinium HR", "Insight Payroll Associates", "Insperity", "Integrated Payroll Services, Inc", "isolved", "isolved Payarc", "isolved(VetPay HCM)", "Justworks", "Keystone Payroll", "KLINGLER & ASSOCIATES, INC.", "Kollath CPA", "Kronos", "Ledger Payroll", "Local Economy Payroll", "Magellan", "Managed Pay", "MassPay, Inc", "Midwest Payroll Services, LLC", "MP HR", "Namely", "NCR/JetPay isolved", "Nevada Payroll Services", "New England Payroll Services", "New England Payroll Solutions", "Newtek", "NEXPAY", "Nexroll Corp", "NextHR", "North West Payroll Solutions, INC.", "Olympic Payroll", "OneSource", "OnPay", "Orkid Solutions, Inc.", "OTP Payroll LLC", "Pacific Employer's Inc", "Pacific Payroll", "Paper Trails", "Partner Paymedia", "Patriot", "PayArc", "Paychex Flex", "Paycom", "Paycor", "PayDataUSA", "Payday Employer Solutions", "PayDay Employer Solutions - Evolution", "Payday Workforce Solutions", "Paylocity", "Paylogics", "Paymaster Pro", "PayMintHR LLC", "PayNW", "PayOptions LLC", "Payority Payroll Solutions", "PayPros Inc.", "Payright", "Payroll & Benefit Solutions", "Payroll Control Systems", "Payroll Dynamics", "Payroll Easy, LLC", "Payroll Factory", "Payroll Network", "Payroll Office of America", "PAYROLL PARTNERS", "Payroll Plus HCM Evolution", "Payroll Plus HCM isolved", "Payroll Relief", "Payroll Solutions (PEO)", "Payroll Solutions HCM", "PAYROLL SOLUTIONS LLC", "Payroll Solutions WA", "Payroll Specialties Inc. isolved", "Payroll Vault", "Payroll Vault - Bowling Green", "Payroll Vault - Corporate", "Payroll Vault - CT", "Payroll Vault - Denver dba TrueInfo LLC", "Payroll Vault - Lansing", "Payroll Vault - Marietta, GA", "Payroll Vault - Penn Yan", "Payroll Vault - Redlands", "Payroll Vault - Richmond", "Payroll Vault - San Antonio", "Payroll Vault - Santa Barbara", "Payroll Vault - South Dakota", "Payroll Vault - St. Petersburg", "Payroll Vault - Venice", "Payroll Vault - Wake Forest/Raleigh", "Payroll Vault Castle Rock", "Payroll Vault Clovis-Fresno", "Payroll Vault Crown Point", "Payroll Vault Grand Island, Nebraska", "Payroll Vault Iowa City", "Payroll Vault Pleasanton", "Payroll Vault Prosper", "Payroll Vault St. Tammany", "Payroll Vault Troy", "Payroll Vault Walnut Creek", "Payroll Vault- Albuquerque", "Payroll Vault-GAAL204", "Payserv Corporation", "PayServ Payroll Solutions", "PaySmart Payroll Services", "PayUSA", "PayWhiz", "PCS HCM", "PeopleKeep", "PeopleWorX", "Performance isolved", "Platinum Group", "PNI•HCM | GovConPay", "Premier HCM", "Press Gold Group", "PrimePay", "Proactive Associates", "Quartermaster Payroll Service", "Quickbooks", "Quickbooks Payroll Core", "Recalibrate HCM", "Reconciled, Inc", "Resourcing Edge", "Rippling", "Rise", "Sage 50 Quantum Accounting", "Sage 50 US Edition Accounting", "Sage Payroll", "SAP SuccessFactors", "Sapling", "Savant HCM Evolution", "Savant HCM isolved", "Simco", "Simplifi Payroll & HR", "SNF Payroll & HR", "Solex HCM", "Square Payroll", "Stewart Lumber", "Strategic isolved", "Stratus HR", "SurePayroll", "Symply", "SyncHR", "Temipay", "Tesseon", "The Human Resource Consulting Group", "The Payroll Company", "The Payroll Department, Inc", "Toast Payroll", "TPC", "TPC The Payroll Company", "TriNet", "Trivantus", "TruPayroll", "UltiPro", "UPsource PEO", "VidaHR", "Viewpoint HR Management Spectrum", "Viewpoint HR Management Vista", "Vital Payroll Advisors, LLC", "Wagepoint", "Wave", "Wayroll HR", "WebHR", "Whirks", "Whois Payroll", "Willhite Business Solutions", "Wipfli", "Workday", "workful llc", "WorkStream", "wurk", "Xero", "Zeal Payroll", "Zenefits", "Zoho Payroll", "Zynergia PEO" ], "description": "Name of the company's payroll provider." }, "naics_code": { "type": "string", "minLength": 1, "description": "6-digit NAICS industry classification code. Must be a valid code accepted on IRS Form 5500.", "maxLength": 6 }, "control_group": { "type": "boolean", "description": "Set to true if this company is part of a controlled group or affiliated service group (ASG)." }, "entity_type": { "type": "string", "enum": [ "C Corporation", "S Corporation", "Non profit", "Partnership", "LLC taxed as S Corp", "LLC taxed as C Corp", "LLC taxed as Partnership", "LLC taxed as Sole Proprietor", "Limited Liability Partnership", "Sole Proprietorship", "Government agency" ], "description": "Legal entity type of the company (e.g., Corporation, LLC, Partnership)." }, "entity_state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WV", "WI", "WY", "DC", "WA", "PR", "VI", "GU", "PW", "FM", "MP", "MH", "AS", "AE", "AA", "AP" ], "description": "State or territory where the company is incorporated or primarily operates." }, "plan_name": { "type": "string", "minLength": 1, "description": "Name of the 401(k) plan. Follows the same character rules as company_name.", "maxLength": 100 }, "plan_type": { "enum": [ "Yes - safe harbor match", "Yes - nonelective contribution", "Yes - QACA safe harbor match", "Yes - enhanced safe harbor match", "No", "Starter-K", "Solo-K" ], "type": "string", "x-spec-enum-id": "86519a9135c99a99", "description": "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.\n\n* `Yes - safe harbor match` - Yes - safe harbor match\n* `Yes - nonelective contribution` - Yes - nonelective contribution\n* `Yes - QACA safe harbor match` - Yes - QACA safe harbor match\n* `Yes - enhanced safe harbor match` - Yes - enhanced safe harbor match\n* `No` - No\n* `Starter-K` - Starter-K\n* `Solo-K` - Solo-K" }, "automatic_enrollment_percentage": { "type": "string", "enum": [ 0, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "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": { "type": "string", "enum": [ 10, 11, 12, 13, 14, 15 ], "description": "Maximum percentage to which automatic annual escalation can increase the deferral rate. Requires a non-zero automatic_enrollment_percentage." }, "plan_effective_date": { "type": "string", "format": "date", "description": "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": { "type": "string", "enum": [ "W-2", "Withholding", "Section 415", "Section 415 Safe Harbor" ], "description": "How employee compensation is defined for contribution calculations." }, "safe_harbor_exclude_hce_and_key": { "type": "boolean", "description": "Whether to exclude Highly Compensated Employees (HCEs) and key employees from safe harbor contributions. Only applicable to safe harbor plan types." }, "service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible to defer." }, "match_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for employer match contributions." }, "profit_sharing_service_requirement": { "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": "Minimum service period an employee must complete before becoming eligible for profit sharing contributions." }, "vesting_schedule": { "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": "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": { "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": "Vesting schedule for profit sharing contributions." }, "profit_sharing_requires_employment_on_last_day": { "type": "boolean", "description": "Whether employees must be employed on the last day of the plan year to receive profit sharing contributions." }, "deferral_change_frequency": { "type": "string", "enum": [ "Each pay period", "Monthly", "Quarterly" ], "description": "How frequently employees are permitted to change their deferral percentage." }, "deferral_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to begin deferring into the plan." }, "employer_match_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive employer match contributions." }, "profit_sharing_entry_frequency": { "type": "string", "enum": [ "Immediate", "Monthly", "Quarterly", "Semi-Annually", "Annually" ], "description": "How frequently new employees become eligible to receive profit sharing contributions." }, "allow_participant_loans": { "type": "boolean", "description": "Whether participants are permitted to take loans from their plan accounts." }, "deferral_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible to defer." }, "employer_match_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for employer match." }, "profit_sharing_minimum_age": { "type": "integer", "description": "Minimum age (18–21 inclusive) an employee must reach before becoming eligible for profit sharing." }, "employer_match_tiers": { "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" ] }, "description": "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." }, "non_elective_contribution": { "type": "integer", "description": "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": { "type": "string", "enum": [ "Weekly", "Bi-Weekly", "Semi-Monthly", "Monthly" ], "description": "How often the company runs payroll. If providing this field you must also provide next_payroll_date." }, "next_payroll_date": { "type": "string", "format": "date", "description": "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": { "type": "integer", "description": "Approximate number of current employees. Used to determine SECURE 2.0 automatic enrollment exemptions." }, "grandfather_existing_employees": { "type": "boolean", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "format": "date", "description": "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": { "type": "string", "nullable": true, "description": "ID of the 3(38) investment advisor to associate with this plan. Retrieve this ID from the affiliate-firms//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": { "type": "string", "nullable": true, "description": "ID of the pricing tier to apply to this plan. Retrieve this ID from the affiliate-firms//pricing-tiers/ or affiliates//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": { "type": "string", "nullable": true, "description": "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": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "company_name", "primary_contact_email", "primary_contact_name" ] }, "PooledPlan": { "type": "object", "properties": { "object_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 }, "effective_date": { "type": "string", "format": "date", "nullable": true }, "terminated_date": { "type": "string", "format": "date", "nullable": true }, "status": { "enum": [ "DRAFT", "ACTIVE", "INACTIVE" ], "type": "string", "description": "* `DRAFT` - DRAFT\n* `ACTIVE` - ACTIVE\n* `INACTIVE` - INACTIVE", "x-spec-enum-id": "8b036d93c4c21fd8" }, "matrix_alliance_code": { "type": "string", "maxLength": 16 } }, "required": [ "name", "object_id" ] }, "PortfolioHistory": { "type": "object", "description": "Portfolio information for a single day.", "properties": { "investments": { "type": "array", "items": { "type": "object", "description": "Investment information for a single day in portfolio history.", "properties": { "object_id": { "type": "string", "description": "The object_id of the associated Investment" }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,3})?$" }, "share_price": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,9}(?:\\.\\d{0,9})?$" }, "basis": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" }, "proceeds": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "basis", "object_id", "proceeds", "share_price", "shares" ] } }, "date": { "type": "string", "format": "date" }, "cash": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,10}(?:\\.\\d{0,2})?$" } }, "required": [ "cash", "date", "investments" ] }, "PortfolioInvestment": { "type": "object", "properties": { "percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$" }, "investment": { "allOf": [ { "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", "nullable": true, "maxLength": 20 }, "description": { "type": "string" }, "asset_class": { "type": "string", "description": "The asset class category of the investment." }, "cusip": { "type": "string", "nullable": true, "maxLength": 9 }, "status": { "enum": [ 1, 2, 3, 4, 50, 100 ], "type": "integer", "description": "* `1` - Active\n* `2` - Inactive\n* `3` - Close Only\n* `4` - Halted\n* `50` - Ambiguous Isin\n* `100` - Unknown", "x-spec-enum-id": "c4eae5f1054b2e9d", "default": "Unknown" } }, "required": [ "asset_class", "description", "object_id" ] } ], "readOnly": true }, "shares": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "value": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "readOnly": true }, "status": { "enum": [ "PENDING_SALE", "ACTIVE" ], "type": "string", "description": "* `PENDING_SALE` - Pending Sale\n* `ACTIVE` - Active", "x-spec-enum-id": "a442a24a44038e9a", "readOnly": true } }, "required": [ "investment", "percent", "shares", "status", "value" ] }, "PortfolioSettings": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "is_rebalancing": { "type": "boolean", "readOnly": true }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "can_cancel_rebalance": { "type": "boolean", "readOnly": true }, "next_trading_window": { "type": "string", "format": "date-time", "readOnly": true }, "self_direct_allowed": { "type": "boolean", "readOnly": true }, "opted_in_to_self_direct": { "type": "boolean" } }, "required": [ "can_cancel_rebalance", "is_rebalancing", "next_trading_window", "self_direct_allowed" ] }, "PortfolioSettingsRequest": { "type": "object", "properties": { "auto_rebalance": { "type": "boolean" }, "rebalance_percent": { "type": "integer", "maximum": 32767, "minimum": -32768 }, "opted_in_to_self_direct": { "type": "boolean" } } }, "PortfolioUpdateRequest": { "type": "object", "properties": { "investments": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "List of investment IDs" }, "weights": { "type": "array", "items": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,6}(?:\\.\\d{0,6})?$" }, "description": "List of investment weights. The order of weights must parallel the order of investments." } }, "required": [ "investments", "weights" ] }, "RetirementDefaults": { "type": "object", "properties": { "age": { "type": "integer", "maximum": 115, "minimum": 18, "description": "Defaults to participant's age" }, "retirement_age": { "type": "integer", "maximum": 115, "minimum": 18, "description": "Defaults to participant's retirement age" }, "salary": { "type": "integer", "minimum": 0, "description": "Defaults to participant's previous year compensation or estimation based on this year" }, "current_savings": { "type": "integer", "minimum": 0, "description": "Defaults to participant's current account balance" }, "savings_percent": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "description": "Percentage of income saved" }, "annual_raise": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "2.00", "description": "Expected annual raise" }, "inflation": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "2.00", "description": "Expected annual inflation" }, "correct_for_inflation": { "type": "boolean", "default": true, "description": "Display amounts as they are worth today" }, "investment_return": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "5.00", "description": "Expected annual investment return" }, "life_expectancy": { "type": "integer", "default": 90 }, "retirement_spending": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$", "default": "70.00", "description": "Percentage of income needed during retirement" }, "include_contributions": { "type": "boolean", "default": true, "description": "Include employer contributions to the account" }, "include_social_security": { "type": "boolean", "default": true }, "under_50_contribution_limit": { "type": "integer", "readOnly": true }, "over_50_contribution_limit": { "type": "integer", "readOnly": true } }, "required": [ "over_50_contribution_limit", "under_50_contribution_limit" ] }, "RetirementEstimate": { "type": "object", "properties": { "age": { "type": "integer" }, "estimated_balance": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "target_savings": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$" }, "social_security": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,18}(?:\\.\\d{0,2})?$", "nullable": true, "description": "Estimated annual amount of social security received. This figure is already included into the estimated_balance." } }, "required": [ "age", "estimated_balance", "social_security", "target_savings" ] }, "SelectAdvisorModelRequestRequest": { "type": "object", "properties": { "selected_model": { "type": "string", "minLength": 1 } }, "required": [ "selected_model" ] }, "Totals": { "type": "object", "properties": { "pretax_ytd": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true }, "posttax_ytd": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true }, "company_contributions_ytd": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true }, "annual_income": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Expected total annual income based on prior years." }, "annual_income_ytd": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Annual income earned year-to-date." }, "total_balance": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Total account balance, including all investments and cash." }, "cash_balance": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Cash balance in the account." }, "year_payroll_count": { "type": "integer", "minimum": 0.0, "description": "Number of expected payrolls in a year." }, "loans": { "type": "array", "items": { "type": "object", "properties": { "loan_balance": { "type": "number", "format": "double", "readOnly": true }, "issue_date": { "type": "string", "format": "date" }, "first_payment_date": { "type": "string", "format": "date", "nullable": true }, "years_duration": { "type": "integer", "readOnly": true } }, "required": [ "first_payment_date", "issue_date", "loan_balance", "years_duration" ] } }, "year_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Participant contribution limits for the year." }, "pre_tax_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Pre-tax contribution limits for the year." }, "post_tax_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Post-tax contribution limits for the year." }, "pre_tax_catch_up_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Pre-tax catch-up contribution limits for the year." }, "post_tax_catch_up_contribution_limit": { "type": "number", "format": "double", "maximum": 10000000000, "minimum": 0.0, "exclusiveMaximum": true, "description": "Post-tax catch-up contribution limits for the year." } }, "required": [ "annual_income", "annual_income_ytd", "cash_balance", "company_contributions_ytd", "loans", "posttax_ytd", "pretax_ytd", "total_balance", "year_payroll_count" ] } }, "securitySchemes": { "knoxApiToken": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Token-based authentication with required prefix \"Token\"" }, "oauth2": { "type": "http", "scheme": "bearer", "description": "OAuth 2.0 Bearer based with an existing token. Enter a token retrieved via the regular OAuth flow elsewhere." } } } }