{"openapi":"3.0.2","info":{"title":"401GO API Documentation","version":"0.0.2","description":"<h1>Authorization</h1>\n\nAll queries below require an authorization header that will look something like&#58; \"Authorization&#58; Token fed88009977c45b25741bt8bec8df02e9cacf438\"\n\nCompanies integrating with 401GO will obtain this token directly from 401GO. This token may be assigned permissions to work for multiple clients at 401GO, eliminating the need to store a token for each client. i.e. If you have three clients in mutual with 401GO, you will only need one token to push and pull information for all three mutual clients. You will use unique company identifiers to specify which company you are pulling or pushing information for. See the /api/companies/ endpoint below for more information.\n"},"tags":[{"name":"Company Information"},{"name":"Participants"},{"name":"Payroll"}],"paths":{"/api/{company_id}/deferrals/":{"get":{"tags":["Participants"],"operationId":"List Deferrals","description":"Return a list of all participant deferrals associated with the company_id passed in. The company_id can be obtained using the /api/companies/ endpoint.\n","parameters":[{"name":"company_id","in":"path","required":true,"description":"Identifies the company for which participant deferrals are desired.","schema":{"type":"string"},"allowEmptyValue":true}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"allOf":[{"type":"object","properties":{"participant_id":{"type":"string"}}},{"type":"object","properties":{"deferrals":{"type":"array","items":{"allOf":[{"allOf":[{"type":"object","properties":{"investment_type":{"type":"string"}}},{"type":"object","properties":{"deferral_type":{"type":"string"}}},{"type":"object","properties":{"amount":{"type":"string"}}}]},{"allOf":[{"type":"object","properties":{"investment_type":{"type":"string"}}},{"type":"object","properties":{"deferral_type":{"type":"string"}}},{"type":"object","properties":{"amount":{"type":"string"}}}]},{"allOf":[{"type":"object","properties":{"investment_type":{"type":"string"}}},{"type":"object","properties":{"deferral_type":{"type":"string"}}},{"type":"object","properties":{"amount":{"type":"string"}}}]}]}}}}]},{"allOf":[{"type":"object","properties":{"participant_id":{"type":"string"}}},{"type":"object","properties":{"deferrals":{"type":"array","items":{"allOf":[{"allOf":[{"type":"object","properties":{"investment_type":{"type":"string"}}},{"type":"object","properties":{"deferral_type":{"type":"string"}}},{"type":"object","properties":{"amount":{"type":"string"}}}]},{"allOf":[{"type":"object","properties":{"investment_type":{"type":"string"}}},{"type":"object","properties":{"deferral_type":{"type":"string"}}},{"type":"object","properties":{"amount":{"type":"string"}}}]},{"allOf":[{"type":"object","properties":{"investment_type":{"type":"string"}}},{"type":"object","properties":{"deferral_type":{"type":"string"}}},{"type":"object","properties":{"amount":{"type":"string"}}}]}]}}}}]}]}},"example":[{"participant_id":"lrio5has","deferrals":[{"investment_type":"pre-tax","deferral_type":"percent","amount":"3.00"},{"investment_type":"pre-tax","deferral_type":"dollar","amount":"0.00"},{"investment_type":"post-tax","deferral_type":"percent","amount":"0.00"},{"investment_type":"post-tax","deferral_type":"dollar","amount":"0.00"}]},{"participant_id":"ctxy841t","deferrals":[{"investment_type":"pre-tax","deferral_type":"percent","amount":"3.00"},{"investment_type":"pre-tax","deferral_type":"dollar","amount":"0.00"},{"investment_type":"post-tax","deferral_type":"percent","amount":"0.00"},{"investment_type":"post-tax","deferral_type":"dollar","amount":"0.00"}]},{"participant_id":"bk04t25o","deferrals":[{"investment_type":"pre-tax","deferral_type":"percent","amount":"3.00"},{"investment_type":"pre-tax","deferral_type":"dollar","amount":"0.00"},{"investment_type":"post-tax","deferral_type":"percent","amount":"0.00"},{"investment_type":"post-tax","deferral_type":"dollar","amount":"0.00"}]}]}},"description":"Request was successful, returned all participants and associated deferrals. Each participant will have four deferrals, two post-tax and two pre-tax. All fields returned below contain strings.\n\nAll fields in this response contain string values. The 'participant_id' field uniquely identifies each participant in 401GO. Each participant has four deferrals. They are separated into pre-tax(traditional) and post-tax(roth) deferrals. Each deferral is either a dollar amount or percentage. A participant may have both pre and post tax deferrals, but they may not have both a dollar amount and a percentage for the same type of deferral. i.e. If a participant has a pre-tax percent deferral with 'amount&#58; 3.00.' Their pre-tax dollar deferral will automatically be 'amount&#58; 0' This applies to post-tax deferrals as well. \n\nIf a deferral has a 'deferral_type' of 'percent' then the 'amount' field is a percentage. i.e. A post-tax percentage deferral with 'amount&#58; 3.00' is a 3% post-tax deferral. If the 'deferral_type' field is 'dollar', then the 'amount' field translates directly to the decimal dollar amount. i.e. A pre-tax dollar deferral with 'amount&#58; 50.50' is a $50.50 pre-tax deferral.\n"},"403":{"content":{"application/json":{"example":{"detail":"Invalid token."}}},"description":"Please check to make sure access token is formatted correctly and included in the request as the 'Authorization' header."},"404":{"description":"Please check the URL to make sure it is formatted correctly."},"405":{"content":{"application/json":{"example":{"detail":"Method not allowed."}}},"description":"The only request method currently available for this endpoint is GET"}}}},"/api/companies/":{"get":{"tags":["Company Information"],"operationId":"List Companies","description":"Get a list of all companies that the access token included in request has permission to access. The unique identifiers obtained from this endpoint will be used in the paths of other endpoints, for example, if you wanted to retreive participant deferrals for 'The Empire' you would substitute the empire's unique identifier for the company_id in the deferrals endpoint as follows&#58; /api/zsunr24b/deferrals/ \n","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string"}}},"example":{"The Empire":"zsunr24b","Rebel Alliance":"n1ghkj6x"}}},"description":"Successfully returns a mapping containing the names and unique identifiers for each company that the access token included in the request has permission to access."},"403":{"content":{"application/json":{"example":{"detail":"Invalid token."}}},"description":"Please check to make sure access token is formatted correctly and included in the request as the 'Authorization' header."},"404":{"description":"Please check the URL to make sure it is formatted correctly."},"405":{"content":{"application/json":{"example":{"detail":"Method not allowed."}}},"description":"The only request method available for this endpoint is GET"}}}},"/api/{company_id}/participants/":{"get":{"tags":["Participants"],"operationId":"List Participants","description":"List all participants associated with company_id passed in. The company_id can be obtained using the /api/companies/ endpoint.","parameters":[{"name":"company_id","in":"path","required":true,"description":"Identifies the company for which participant info is desired.","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"type":"object","properties":{"name":{"type":"string"}}},{"type":"object","properties":{"start_date":{"type":"string"}}},{"type":"object","properties":{"termination_date":{"type":"string"}}},{"type":"object","properties":{"ssn":{"type":"string"}}},{"type":"object","properties":{"dob":{"type":"string"}}},{"type":"object","properties":{"phone":{"type":"string"}}},{"type":"object","properties":{"email":{"type":"string"}}},{"type":"object","properties":{"participant_id":{"type":"string"}}},{"type":"object","properties":{"address":{"allOf":[{"type":"object","properties":{"name_line_1":{"type":"string"}}},{"type":"object","properties":{"name_line_2":{"type":"string"}}},{"type":"object","properties":{"address_line_1":{"type":"string"}}},{"type":"object","properties":{"address_line_2":{"type":"string"}}},{"type":"object","properties":{"city":{"type":"string"}}},{"type":"object","properties":{"state":{"type":"string"}}},{"type":"object","properties":{"postal_code":{"type":"string"}}},{"type":"object","properties":{"country":{"type":"string"}}}]}}}]}},"example":[{"name":"Big Bad Wolf","start_date":"2020-01-01","termination_date":null,"ssn":"123456789","dob":"2020-04-01","phone":"1234567890","email":"BigBadWolf@sharklasers.com","participant_id":"lrio5has","address":{"name_line_1":"address nickname","name_line_2":"","address_line_1":"8493 N Forest Dr","address_line_2":"","city":"Santa Fe","state":"NM","postal_code":"87505","country":"US"}},{"name":"Employee Name","start_date":"2020-02-20","termination_date":null,"ssn":"123456789","dob":"1921-02-16","phone":"","email":"employee@401go.com","participant_id":"ctxy841t","address":{"name_line_1":"Address nickname","name_line_2":"","address_line_1":"8427 S Old Bingham HWY","address_line_2":"","city":"West Jordan","state":"UT","postal_code":"84088","country":"USA"}}]}},"description":"Most of the fields will be available most of the time, however, the only fields guaranteed to be present are participant_id, name, and some form of communication(email or phone). \n\nAll fields are always strings except for termination_date, which may be null if the employee is currently active.\n"},"403":{"content":{"application/json":{"example":{"detail":"Invalid token."}}},"description":"Please check to make sure access token is formatted correctly and included in the request as the 'Authorization' header."},"404":{"description":"Please check the URL to make sure it is formatted correctly."},"405":{"content":{"application/json":{"example":{"detail":"Method not allowed."}}},"description":"The only request method currently available for this endpoint is GET"}}}},"/api/{company_id}/payrolls/":{"post":{"tags":["Payroll"],"operationId":"Create Payroll","description":"Submit payroll information to 401GO for whatever company is associated with the company_id passed in. The company_id can be obtained using the /api/companies/ endpoint.","parameters":[{"name":"company_id","in":"path","required":true,"description":"Identifies the company for which payroll is being run.","schema":{"type":"string"}}],"requestBody":{"description":"Any fields describing hours worked or pay garnered should be decimal numbers. All other fields should be strings. The field 'payroll_type' should either be 'REGULAR' or 'OFF_CYCLE'. pay_period_start and pay_period_end should follow the format of 'year-month-day'. payroll_type doesn't have to be included if both pay_period_start and pay_period_end are included(payroll_type will just default to REGULAR), and if payroll_type is included and set to 'OFF_CYCLE' then pay_period_start and pay_period_end do not have to be included. You can also just include all three if that is easiest. If you are correcting a previous payroll then set payroll_type to 'OFF_CYCLE' and set pay_period_start and pay_period_end to the dates in the previous payroll.\n\nThe hours and gross_pay fields for each participant describe the hours worked and pay garnered for the current pay period. Each participant requires the participant_code, hours, and gross_pay fields. The hours_ytd and gross_pay_ytd fields are not required, but you may include them.\n\nLastly, you may submit more than one payroll at a time, as shown in the example value below. You may submit as many payrolls as you like as long as they follow the format outlined above and the example shown below.\n","content":{"application/json":{"schema":{"type":"object","properties":{"payroll_type":{"type":"string"},"pay_period_start":{"type":"string"},"pay_period_end":{"type":"string"},"participants":{"type":"array","items":{"allOf":[{"type":"object","properties":{"participant_code":{"type":"string"}}},{"type":"object","properties":{"hours":{"type":"string"}}},{"type":"object","properties":{"gross_pay":{"type":"string"}}},{"type":"object","properties":{"hours_ytd":{"type":"string"}}},{"type":"object","properties":{"gross_pay_ytd":{"type":"string"}}}]}}}},"example":[{"payroll_type":"REGULAR","pay_period_start":"2020-1-16","pay_period_end":"2020-1-30","participants":[{"participant_code":"lrio5has","hours":9,"gross_pay":700,"hours_ytd":5,"gross_pay_ytd":5000.99},{"participant_code":"ctxy841t","hours":200,"gross_pay":80,"hours_ytd":2,"gross_pay_ytd":25000.99},{"participant_code":"bk04t25o","hours":2000,"gross_pay":9,"hours_ytd":2045,"gross_pay_ytd":250000.99}]},{"payroll_type":"OFF_CYCLE","participants":[{"participant_code":"lrio5has","hours":2,"gross_pay":80900,"hours_ytd":2,"gross_pay_ytd":25000.99},{"participant_code":"ctxy841t","hours":2,"gross_pay":900,"hours_ytd":7,"gross_pay_ytd":2000.99},{"participant_code":"bk04t25o","hours":900,"gross_pay":89,"hours_ytd":23,"gross_pay_ytd":23000.99}]}]}}},"responses":{"201":{"description":"Created"},"400":{"content":{"application/json":{"example":{"detail":"Please check to make sure JSON is formed properly, all participant/company identifiers are correct, and all field names exactly match the possible field names exactly match the possible field names as outlined in the documentation."}}},"description":"This most frequently occurs when unique identifiers do not match exactly, especially if a participant was just removed from 401GO. For this reason, it is recommended to pull participants every time just before pushing payroll. If this does not fix the issue, please make sure all fields match exactly as outlined in the schema above."},"403":{"content":{"application/json":{"example":{"detail":"Invalid token."}}},"description":"Please check to make sure access token is formatted correctly and included in the request as the 'Authorization' header."},"404":{"description":"Please check the URL to make sure it is formatted correctly."},"405":{"content":{"application/json":{"example":{"detail":"Method not allowed."}}},"description":"The only request method currently available for this endpoint is POST"}}}}}}