{"openapi":"3.0.0","info":{"contact":{"name":"321Forms","email":"support@321forms.com","url":"https://www.321forms.com"},"version":"1.9.2","title":"321Forms API","description":"Public API documentation for the 321Forms onboarding solution"},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/321Forms/321Forms-API-Public/1.9.2"},{"url":"https://api.321forms.com/v1"}],"paths":{"/company.json":{"get":{"summary":"Returns a list of companies that the user can access","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"name":"partial","required":false,"in":"query","description":"searchable partial name of the company","schema":{"type":"string"}},{"name":"offset","required":false,"in":"query","description":"query search offset","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","required":false,"in":"query","description":"maximum returned results","schema":{"type":"integer","default":10,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}}}}}}},"/company/{companyID}/{userType}.json":{"get":{"summary":"List array of users in a company {:companyID} based on {:userType} Provided. Will only show users that the requesting account is allowed to manage","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"},{"$ref":"#/components/parameters/UserTypePathParam"},{"name":"offset","required":false,"in":"query","description":"query search offset","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","required":false,"in":"query","description":"maximum returned results","schema":{"type":"integer","default":10,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"division_id":{"type":"integer"},"first_name":{"type":"string"},"last_name":{"type":"string"},"role":{"type":"string"},"username":{"type":"string"},"date_created":{"type":"string"},"active":{"type":"integer","enum":[0,1]},"deactive_date":{"type":"string"},"email_address":{"type":"string"}}}}}}}}}},"/company/{companyID}/complete.json":{"get":{"summary":"Returns a list of 100% onboarded users in the provided company {:companyID}. Sorted by latest approved form date (provided in response as 'utc_latest_approved_date')","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"},{"name":"offset","required":false,"in":"query","description":"query search offset","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","required":false,"in":"query","description":"maximum returned results","schema":{"type":"integer","default":10,"minimum":1,"maximum":50}},{"name":"show_uid","required":false,"in":"query","description":"Include numeric User ID on return objects","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"division_id":{"type":"integer","minimum":1},"is_active":{"type":"integer","enum":[0,1]},"approved_forms":{"type":"integer"},"total_possible":{"type":"integer"},"total_assigned":{"type":"integer"},"submitted_forms":{"type":"integer"},"household_progress":{"type":"integer"},"percent_total":{"type":"integer"},"progress_towards_completion":{"type":"integer"},"utc_latest_approved_date":{"type":"string"}}}}}}}}}},"/company/{companyID}/forms.json":{"get":{"summary":"Returns an array of the company's forms. This will be used when selecting the forms to provide for a new hire","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"form_id":{"type":"integer","minimum":1},"utc_latest_submission_date":{"type":"string"},"utc_latest_approved_date":{"type":"string"}}}}}}}}}},"/company/{companyID}/form/{formID}.json":{"get":{"summary":"Returns an array of form questions and an object with the basic details of the form itself","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"},{"$ref":"#/components/parameters/FormIDPathParam"},{"$ref":"#/components/parameters/CompanyFormTypeQueryParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CompanyFormQuestionSchema"},{"$ref":"#/components/schemas/CompanyFormPDFSchema"}]},"examples":{"questions":{"summary":"Type = 'questions' or 'resolution'","value":{"form_questions":[{"special_format":"","max_value":"","question_type":"textarea","choices":[],"question_text":"Last Name (without suffix):","question_number":0,"max_length":255,"min_value":""}],"form_details":{"id":0,"name":"W-4 - 2015","description":"Calculates income withheld for federal taxes."}}},"pdf":{"summary":"Type = 'pdf'","value":{"base_64_blank_form":"*URL ENCODED BASE64 DATA*","form_details":{"id":0,"name":"W-4 - 2015","description":"Calculates income withheld for federal taxes."}}}}}}}}}},"/company/{companyID}/divisions.json":{"get":{"summary":"Returns a structure containing two elements. the companyID provided and an array of divisions","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"divisions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"integer"}}}},"companyID":{"type":"integer"}}}}}}}}},"/company/{companyID}/report.json":{"get":{"summary":"Returns an array of report objects","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"integer"}}}}}}}}}},"/company/{companyID}/report/{reportID}.json":{"get":{"summary":"Returns a structure containing two elements. The first is an array of column headers and the second is the array of user responses with the keys equal to those headers","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"},{"$ref":"#/components/parameters/ReportIDPathParam"},{"$ref":"#/components/parameters/ReportStartDateQueryParam"},{"$ref":"#/components/parameters/ReportEndDateQueryParam"},{"$ref":"#/components/parameters/ReportCompleteQueryParam"},{"$ref":"#/components/parameters/ReportEverifyQueryParam"},{"$ref":"#/components/parameters/ReportEIDQueryParam"},{"$ref":"#/components/parameters/ReportDivisionsQueryParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"string"}},"results":{"type":"array","items":{"type":"object","properties":{"ColumnName1":{"type":"string"},"customName2":{"type":"string"}}}}}},"example":{"columns":["Zip Code","First Name","Last Name"],"results":[{"Zip Code":11111,"First Name":"John","Last Name":"Doe"},{"Zip Code":11111,"First Name":"Jane","Last Name":"Doe"}]}}}}}}},"/company/{companyID}/hook.json":{"get":{"summary":"Returns an array of webhooks","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"hash_key":{"type":"string"},"url":{"type":"string"},"id":{"type":"string"},"last_update":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}}}}},"example":[{"hash_key":"02c201d1-1286-48b2-bbfb-89f82a42aca0","url":"https://your.secured-url.com","id":"9d0f3821-9dd5-4537-9f41-626c2fda1be4","last_update":"2018-07-24 20:24 +0000","topics":["All Employee Forms Have Been Submitted","An Employee Form Has Been Approved","An Employee Form Has Been Submitted","An Employee Has Reached 100% Onboarded"]}]}}}}},"post":{"summary":"Inserts a new webhook","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/PostAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostWebhookSchema"},"example":{"url":"https://your.secured-url.com","topics":["5b6f94eb-0c53-45ef-99ab-a654f5d18223","a9b802e9-998e-4230-9d59-ecdcdb3d3fe1","e8883c8e-06f3-4626-a847-9a0630f90f33","599016c8-f6d0-422b-94c7-a9032bda0c35"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnSchema"},"examples":{"success":{"$ref":"#/components/examples/WebhookExampleSchema"}}}}}}}},"/company/{companyID}/hook/{hookID}.json":{"get":{"summary":"Returns information about an existing webhook","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"},{"$ref":"#/components/parameters/HookIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnSchema"},"examples":{"success":{"$ref":"#/components/examples/WebhookExampleSchema"}}}}}}},"put":{"summary":"Update an existing webhook","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/PutAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"},{"$ref":"#/components/parameters/HookIDPathParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostWebhookSchema"},"example":{"url":"https://your.secured-url.com","topics":["5b6f94eb-0c53-45ef-99ab-a654f5d18223","a9b802e9-998e-4230-9d59-ecdcdb3d3fe1","e8883c8e-06f3-4626-a847-9a0630f90f33","599016c8-f6d0-422b-94c7-a9032bda0c35"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnSchema"},"examples":{"success":{"$ref":"#/components/examples/WebhookExampleSchema"}}}}}}},"delete":{"summary":"Deletes an existing webhook","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/DeleteAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"},{"$ref":"#/components/parameters/HookIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/company/{companyID}/hook/topics.json":{"get":{"summary":"Returns an array of available webhook 'topics'","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"simple_key":{"type":"string"},"description":{"type":"string"}}}}}}}}}},"/company/{companyID}/plugins.json":{"get":{"summary":"Returns an array of the company's plugins","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/CompanyIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}},"example":["E-Verify","WOTC Provider Name","Payroll Provider Name"]}}}}}},"/division/{divisionID}.json":{"get":{"summary":"Returns basic details for a given division","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/DivisionIDPathParam"},{"$ref":"#/components/parameters/DivisionListOptionalQueryParams"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"companyID":{"type":"integer"},"name":{"type":"string"},"active":{"type":"boolean"},"[optionalParamData]":{"type":"object"}}},"example":{"companyID":0,"name":"name","active":true,"contact":{"fax":"555-555-0000","phone_ext":"","fax_ext":"","person":"Staff Member","phone":"801-563-5698","email":"fake.email@321forms.com"},"formDefaults":[1,2,3,4,5],"eVerify":{"startDate":"July, 20 2014 23:08:32","set":true,"clientCompanyId":0},"flyers":[{"is_active":true,"name":"Last flyer","id":0,"is_required":false,"description":"some additional details"}],"employeeUploads":[{"validTypes":".txt.pdf.ppt.xls.doc.docx.pptx.xlsx.gif.jpeg.jpg.pjpeg.png","name":"Transcript","id":0,"description":"Some additional details"}],"taxCredits":{"location":"FAKE_LOCATION","client":"FAKE_CLIENT"}}}}}}}},"/division/{divisionID}/{userType}.json":{"get":{"summary":"Returns a list of users for a given division. Response format is the same as 'company/{companyID}/{userType}'","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/DivisionIDPathParam"},{"$ref":"#/components/parameters/UserTypePathParam"},{"name":"offset","required":false,"in":"query","description":"query search offset","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","required":false,"in":"query","description":"maximum returned results","schema":{"type":"integer","default":10,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"first_name":{"type":"string"},"role":{"type":"string"},"id":{"type":"integer"},"username":{"type":"string"},"date_created":{"type":"string"},"active":{"type":"integer"},"deactive_date":{"type":"string"},"last_name":{"type":"string"},"email_address":{"type":"string"},"division_id":{"type":"integer"}}}}}}}}}},"/division/{divisionID}/complete.json":{"get":{"summary":"Returns a list of 100% onboarded users in the provided division {:divisionID}. Sorted by latest approved form date (provided in response as 'utc_latest_approved_date')","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/DivisionIDPathParam"},{"name":"offset","required":false,"in":"query","description":"query search offset","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","required":false,"in":"query","description":"maximum returned results","schema":{"type":"integer","default":10,"minimum":1,"maximum":50}},{"name":"show_uid","required":false,"in":"query","description":"Include numeric User ID on return objects","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"division_id":{"type":"integer","minimum":1},"is_active":{"type":"integer","enum":[0,1]},"approved_forms":{"type":"integer"},"total_possible":{"type":"integer"},"total_assigned":{"type":"integer"},"submitted_forms":{"type":"integer"},"household_progress":{"type":"integer"},"percent_total":{"type":"integer"},"progress_towards_completion":{"type":"integer"},"utc_latest_approved_date":{"type":"string"}}}}}}}}}},"/division/{divisionID}/flyers.json":{"get":{"summary":"Returns an array of the division's flyers","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/DivisionIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DivisionFlyersSchema"}}}}}}},"/division/{divisionID}/flyers/{flyerID}.json":{"get":{"summary":"Returns a specific division flyers","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/DivisionIDPathParam"},{"$ref":"#/components/parameters/FlyerIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DivisionFlyerSchema"},"example":{"data":"[URL ENCODED BASE64 DATA]","file":"MyExampleFlyer.pdf","uploaded":"December, 14 2017 18:30:00 -0600","extension":"application/pdf"}}}}}}},"/division/{divisionID}/forms.json":{"get":{"summary":"Returns an array of the company's forms, with the additional information on which forms are 'selected_as_default' for a division. This will be used when selecting the forms to provide for a new hire. An employee that is to be placed within a certain division should have the defaults selected if provided","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/DivisionIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DivisionFormsSchema"}}}}}}},"/division/{divisionID}/prefill.json":{"get":{"summary":"Returns an array of questions that will be asked of an employee during account creation. These values are used for data that is variable for each employee, but needs to be entered prior to an employee signing their documents","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/DivisionIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PrefillResponseSchema"}}}}}}}},"/users/{userID}.json":{"get":{"summary":"Returns an individual user based on :userID","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/UserIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseSchema"},"example":{"id":0,"first_name":"Testing","last_name":"Employee","username":"testingemployee","active":true,"email_address":"no-reply@321forms.com","roles":{"employee":[{"divisionID":0,"companyID":0}],"staff":[{"divisionID":0},{"companyID":0}]}}}}}}},"post":{"summary":"Creates a new employee based on :userID","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/PostAction"},{"$ref":"#/components/parameters/UserIDPathParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeCreationPostBody"},"example":{"companyID":1,"divisionID":5,"firstName":"Jon","lastName":"Doe","emailAddress":"employee@mycompany.com","forms":[1,2,3,"D"],"responses":[{"id":1,"response":"First Front-End Response"},{"id":2,"response":true}],"isTest":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"SUCCESS":{"type":"boolean"},"USER_ID":{"type":"integer"},"DETAIL":{"type":"string"},"SSO_EMPLOYEE_ID":{"type":"string"},"ALL_RESPONSES_SAVED":{"type":"boolean"},"USERNAME":{"type":"string"},"PASSWORD":{"type":"string"}}},"examples":{"success":{"summary":"Success","value":{"SUCCESS":true,"USER_ID":0,"DETAIL":"Onboard Success","SSO_EMPLOYEE_ID":"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx","ALL_RESPONSES_SAVED":true,"USERNAME":"321Test","PASSWORD":"ARealPasswordWillBeHere"}},"successWithInvalidResponses":{"summary":"Success, but some pre-filled responses are invalid and responseValidation = warn","value":{"SUCCESS":true,"USER_ID":0,"DETAIL":"Onboard Success","SSO_EMPLOYEE_ID":"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx","ALL_RESPONSES_SAVED":true,"USERNAME":"321Test","PASSWORD":"ARealPasswordWillBeHere","WARNINGS":{"INVALID_RESPONSES":[{"response":"agdgdg","error":"The response provided is not a valid Social Security Number","question_no":0}]}}},"unsuccessful":{"summary":"an invalid request prevented the employee from being created","value":{"SUCCESS":false,"USER_ID":0,"DETAIL":"The username provided is unavailable. Please enter another username.","SSO_EMPLOYEE_ID":null,"ALL_RESPONSES_SAVED":null,"USERNAME":"321Test","PASSWORD":null}}}}}}}},"put":{"summary":"Updates an existing employee based on :userID","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/PutAction"},{"$ref":"#/components/parameters/UserIDPathParam"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeCreationPutBody"},"example":{"firstName":"Foo","lastName":"Bar","emailAddress":"no-reply@321forms.com","username":"foo","password":"supersecurepassword","active":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseSchema"},"example":{"id":0,"first_name":"Testing","last_name":"Employee","username":"testingemployee","active":true,"email_address":"no-reply@321forms.com","roles":{"employee":[{"divisionID":0,"companyID":0}],"staff":[{"divisionID":0},{"companyID":0}]}}}}}}}},"/users/{userID}/available.json":{"get":{"summary":"Tests if a username is available for use in a new account","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/UserIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"detail":{"type":"string"}}}}}}}}},"/users/{userID}/everify.json":{"get":{"summary":"Returns the lastest E-Verify case information about an employee","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/UserIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"casenumber":{"type":"string"},"status":{"type":"string"},"authorized":{"type":"boolean"}}}}}}}}},"/users/{userID}/forms.json":{"get":{"summary":"List the forms available to an employee and the UTC Timestamps of the latest submitted and approved versions","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/UserIDPathParam"},{"name":"includeAll","required":false,"in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"utc_latest_submission_date":{"type":"string"},"utc_latest_approved_date":{"type":"string"},"form_id":{"type":"integer"}}}}}}}}}},"/users/{userID}/form/{formID}.json":{"get":{"summary":"Receives response information of a user's latest form of a particular status","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/FormIDPathParam"},{"$ref":"#/components/parameters/UserIDPathParam"},{"$ref":"#/components/parameters/FormTypeQueryParam"},{"$ref":"#/components/parameters/FormStatusQueryParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/FormQuestionSchema"},{"$ref":"#/components/schemas/FormFieldsSchema"},{"$ref":"#/components/schemas/FormPDFSchema"},{"$ref":"#/components/schemas/FormURLSchema"}]},"examples":{"questions":{"summary":"Type = 'questions'","value":{"formID":0,"formInfo":{"utc_submission_timestamp":"July, 20 2014 23:08:32","approved":true,"utc_approved_timestamp":"July, 20 2014 23:08:32","aaid":0},"questions":[{"question_number":0,"response":"sample"}],"userID":{"type":"sample"}}},"fields":{"summary":"Type = 'fields'","value":{"formID":0,"formInfo":{"aaid":0,"approved":true,"utc_submission_timestamp":"July, 20 2014 23:08:32","utc_approved_timestamp":"July, 20 2014 23:08:32"},"fields":[{"name":"sample","value":"sample"}],"userID":{"type":"sample"}}},"pdf":{"summary":"Type = 'pdf'","value":{"formID":0,"formInfo":{"aaid":0,"approved":true,"utc_submission_timestamp":"July, 20 2014 23:08:32","utc_approved_timestamp":"July, 20 2014 23:08:32"},"pdf":{"data":"*URL ENCODED BASE64 DATA*","info":"base64 representation of binary object"},"userID":{"type":"sample"}}},"url":{"summary":"Type = 'url'","value":{"formID":0,"formInfo":{"aaid":0,"approved":true,"utc_submission_timestamp":"July, 20 2014 23:08:32","utc_approved_timestamp":"July, 20 2014 23:08:32"},"url":{"data":"https://..","info":"A temporary URL for your PDF. This link will expire"},"userID":{"type":"sample"}}}}}}}}}},"/users/{userID}/responses.json":{"get":{"summary":"Receives response information to questions asked of a user","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/UserIDPathParam"},{"name":"questions","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer"},"default":"all questions"}},{"name":"offset","required":false,"in":"query","description":"query search offset","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","required":false,"in":"query","description":"maximum returned results","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}}],"responses":{"200":{"description":"Success\n\nTwo important distinctions within the response are:\n1. Responses are represented in an array in case of multi-select options, and\n2. All responses will have leading and trailing spaces to ensure that response data is not mis-cast (for example: SSN 000000007 may be cast as 7 if not for spaces)\"\n","content":{"application/json":{"schema":{"type":"object","properties":{"responses":{"type":"array","items":{"type":"string"}},"question_text":{"type":"string"},"question_number":{"type":"integer"}}},"example":{"responses":[" 000000007 "],"question_text":"SSN","question_number":0}}}}}}},"/users/{userID}/basicInformation.json":{"get":{"summary":"Receives basic user information for an employee's account","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/UserIDPathParam"},{"name":"fw","required":false,"in":"query","description":"show information about federal withholding","schema":{"type":"boolean","default":false}},{"name":"sw","required":false,"in":"query","description":"show information about state withholding","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Success\n* **federal** - will appear when fw=true\n* **state** - will appear when sw=true\n","content":{"application/json":{"schema":{"type":"object","properties":{"basic":{"type":"object","properties":{"emailAddress":{"type":"string"},"lastName":{"type":"string"},"zipCode":{"type":"string"},"homePhone":{"type":"string"},"gender":{"type":"string"},"birthDate":{"type":"string"},"state":{"type":"string"},"firstName":{"type":"string"},"streetAddress":{"type":"string"},"middleInitial":{"type":"string"},"city":{"type":"string"}}},"federal":{"type":"object","properties":{"allowances":{"type":"string"},"otherIncome":{"type":"string"},"multiJobs":{"type":"string"},"deductions":{"type":"string"},"maritalStatus":{"type":"string"},"employerAddress":{"type":"string"},"lastName":{"type":"string"},"extraWithholding":{"type":"string"},"submissionDate":{"type":"string"},"aptNum":{"type":"string"},"additionalWithholding":{"type":"string"},"zipCode":{"type":"string"},"employerFein":{"type":"string"},"increaseWithholding":{"type":"boolean"},"state":{"type":"string"},"firstName":{"type":"string"},"streetAddress":{"type":"string"},"middleInitial":{"type":"string"},"signature":{"type":"string"},"socSecNum":{"type":"string"},"lastNameDiffer":{"type":"string"},"city":{"type":"string"},"nameOfEmployer":{"type":"string"},"dependentTaxCredit":{"type":"string"},"exempt":{"type":"string"}}},"state":{"type":"object","properties":{"residentWithholding":{"type":"string"},"workState":{"type":"string"},"w4OnFile":{"type":"string"},"workWithholding":{"type":"string"},"stateOfResidence":{"type":"string"},"workExemptions":{"type":"string"},"secondaryAllowances":{"type":"string"},"w4FilingYear":{"type":"string"},"residentFilingStatus":{"type":"string"},"overrideAmountOrPercentage":{"type":"string"},"w4State":{"type":"string"},"workFilingStatus":{"type":"string"},"yonkersAdditionalWithholdings":{"type":"string"},"residentIsexempt":{"type":"string"},"primaryAllowances":{"type":"string"},"filingStatus":{"type":"string"},"workIsexempt":{"type":"string"},"residentExemptions":{"type":"string"},"nysAdditionalWithholdings":{"type":"string"},"overrideType":{"type":"string"},"isExempt":{"type":"string"},"residentState":{"type":"string"},"numberOfExemptions":{"type":"string"},"supplementalExemptions":{"type":"string"},"w4ResidentState":{"type":"string"},"nycAdditionalWithholdings":{"type":"string"}}}}}}}}}}},"/users/{userID}/uploads.json":{"get":{"summary":"List the uploaded documents associated with the employee's account","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/UserIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"utc_upload_timestamp":{"type":"string"},"category":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"}}}}}}}}}},"/users/{userID}/uploads/{fileID}.json":{"get":{"summary":"Grabs an individual uploaded document","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/UserIDPathParam"},{"$ref":"#/components/parameters/FileIDPathParam"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"data":{"type":"string"},"utc_upload_timestamp":{"type":"string"},"category":{"type":"string"},"name":{"type":"string"},"extension":{"type":"string"},"description":{"type":"string"}}}}}}}}}},"/SSO/generate.json":{"get":{"summary":"Returns a simple object with the variable :SSOKey that can be used to initiate a single sign-on account for a user","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"SSOKEY":{"type":"string"}}}}}}}}},"/SSO/{EmployeeCFUUID}.json":{"post":{"summary":"Returns an object that includes the endpoint to contiune with the SSO process. You must register your application as an SSO Provider with 321Forms prior to utilizing this endpoint","parameters":[{"$ref":"#/components/parameters/Username"},{"$ref":"#/components/parameters/SentDate"},{"$ref":"#/components/parameters/GetAction"},{"$ref":"#/components/parameters/EmployeeCFUUIDIDPathParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeCFUUIDIDRedirectPostBody"},"example":{"redirect":{"action":"employee-folder","id":0}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string"},"confirmed":{"type":"boolean"}}},"example":{"endpoint":"https://my.321forms.com/some/url/path","confirmed":true}}}}}}}},"components":{"securitySchemes":{"Authorization":{"description":"NSA SHA-1 Encrypted Header","type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"CompanyFormTypeQueryParam":{"in":"query","name":"type","required":false,"schema":{"type":"string","default":"questions","enum":["questions","pdf","resolution","signature"]},"description":"The type of response you want for the form you are selecting. 'questions' refers to questions asked to employees. 'resolution' refers to questions asked to managers when approving the form. 'signature' refers to electronic signature questions when the employee is signing forms."},"Username":{"name":"Username","required":true,"in":"header","description":"Username of individual responsible for the call","schema":{"type":"string"}},"SentDate":{"name":"SentDate","required":true,"in":"header","description":"UTC Timestamp request of when header was created. The call will not be accepted if this timestamp is more than 10 minutes old","schema":{"type":"string"}},"GetAction":{"name":"Action","required":true,"in":"header","description":"REST action type","schema":{"type":"string","enum":["GET"]}},"PostAction":{"name":"Action","required":true,"in":"header","description":"REST action type","schema":{"type":"string","enum":["POST"]}},"DeleteAction":{"name":"Action","required":true,"in":"header","description":"REST action type","schema":{"type":"string","enum":["DELETE"]}},"PutAction":{"name":"Action","required":true,"in":"header","description":"REST action type","schema":{"type":"string","enum":["PUT"]}},"CompanyIDPathParam":{"in":"path","name":"companyID","required":true,"schema":{"type":"integer","minimum":1},"description":"The Company ID"},"DivisionIDPathParam":{"in":"path","name":"divisionID","required":true,"schema":{"type":"integer","minimum":1},"description":"The Division ID"},"DivisionListOptionalQueryParams":{"in":"query","name":"params","required":false,"schema":{"type":"array","items":{"type":"string","enum":["flyers","uploads","defaults","everify","wotc","contact"]}}},"EmployeeCFUUIDIDPathParam":{"in":"path","name":"EmployeeCFUUID","required":true,"schema":{"type":"string"},"description":"The CF UUID Mapped to an Employee"},"FileIDPathParam":{"in":"path","name":"fileID","required":true,"schema":{"type":"integer","minimum":1},"description":"The File ID"},"FlyerIDPathParam":{"in":"path","name":"flyerID","required":true,"schema":{"type":"integer","minimum":1},"description":"The Flyer ID"},"FormIDPathParam":{"in":"path","name":"formID","required":true,"schema":{"type":"integer","minimum":1},"description":"The Form ID"},"FormStatusQueryParam":{"in":"query","name":"status","required":false,"schema":{"type":"string","default":"approved","enum":["approved","submitted"]},"description":"The current status of form you are selecting"},"FormTypeQueryParam":{"in":"query","name":"type","required":false,"schema":{"type":"string","default":"questions","enum":["questions","fields","pdf","url"]},"description":"The type of response you want for the form you are selecting"},"HookIDPathParam":{"in":"path","name":"hookID","required":true,"schema":{"type":"integer","minimum":1},"description":"The Webhook ID"},"ReportIDPathParam":{"in":"path","name":"reportID","required":true,"schema":{"type":"integer","minimum":1},"description":"The Customer Report ID"},"ReportStartDateQueryParam":{"in":"query","name":"startDate","required":false,"schema":{"type":"string","default":"1 week from today"},"description":"first date of approval of a form"},"ReportEndDateQueryParam":{"in":"query","name":"endDate","required":false,"schema":{"type":"string","default":"current date"},"description":"last date of approval of a form"},"ReportCompleteQueryParam":{"in":"query","name":"complete","required":false,"schema":{"type":"boolean","default":false},"description":"return only 100% complete employees"},"ReportEverifyQueryParam":{"in":"query","name":"everify","required":false,"schema":{"type":"boolean","default":false},"description":"return only employees that have e-verify case numbers"},"ReportEIDQueryParam":{"in":"query","name":"eid","required":false,"schema":{"type":"boolean","default":false},"description":"append auto-generated EIDs to the report"},"ReportDivisionsQueryParam":{"in":"query","name":"divisions","required":false,"schema":{"type":"array","default":"all divisions","items":{"type":"integer"}},"description":"List of divisions to search"},"UserIDPathParam":{"in":"path","name":"userID","required":true,"schema":{"type":"integer","minimum":1},"description":"The User ID"},"UserTypePathParam":{"in":"path","name":"userType","required":true,"schema":{"type":"string","enum":["employee","admin","reseller","hrAdmin","staff"]},"description":"Role Type of User"}},"schemas":{"CompanyFormQuestionSchema":{"description":"when {type} parameter equals 'questions'","type":"object","properties":{"form_questions":{"type":"array","items":{"type":"object","properties":{"special_format":{"type":"string"},"question_type":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}},"question_text":{"type":"string"},"question_number":{"type":"integer"},"min_value":{"type":"string"},"max_value":{"type":"string"},"max_length":{"type":"integer"}}}},"form_details":{"type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"},"name":{"type":"string"}}}}},"CompanyFormPDFSchema":{"description":"when {type} parameter equals 'pdf'","type":"object","properties":{"base_64_blank_form":{"type":"string"},"form_details":{"type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"},"name":{"type":"string"}}}}},"DivisionFlyersSchema":{"description":"An array of flyers and their IDs can be retrieved for a division.","type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"},"name":{"type":"string"}}}},"DivisionFlyerSchema":{"description":"An object of flyer data.","type":"object","properties":{"data":{"type":"string"},"file":{"type":"string"},"uploaded":{"type":"string"},"extension":{"type":"string"}}},"DivisionFormsSchema":{"description":"An array of forms and their IDs can be retrieved for a company.","type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"},"name":{"type":"string"},"selected_as_default":{"type":"boolean"}}}},"FormQuestionSchema":{"description":"when {type} parameter equals 'questions'","type":"object","properties":{"formID":{"type":"integer"},"formInfo":{"type":"object","properties":{"utc_submission_timestamp":{"type":"string"},"approved":{"type":"boolean"},"utc_approved_timestamp":{"type":"string"},"aaid":{"type":"integer"}}},"questions":{"type":"array","items":{"type":"object","properties":{"question_number":{"type":"number"},"response":{"type":"string"}}}},"userID":{"type":"string"}}},"FormFieldsSchema":{"description":"when {type} parameter equals 'fields'","type":"object","properties":{"formID":{"type":"integer"},"formInfo":{"type":"object","properties":{"aaid":{"type":"integer"},"approved":{"type":"boolean"},"utc_submission_timestamp":{"type":"string"},"utc_approved_timestamp":{"type":"string"}}},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"FormPDFSchema":{"description":"when {type} parameter equals 'pdf'","type":"object","properties":{"formID":{"type":"integer"},"pdf":{"type":"object","properties":{"data":{"type":"string"},"info":{"type":"string"}}},"formInfo":{"type":"object","properties":{"utc_submission_timestamp":{"type":"string"},"approved":{"type":"boolean"},"utc_approved_timestamp":{"type":"string"},"aaid":{"type":"integer"}}},"userID":{"type":"string"}}},"FormURLSchema":{"description":"when {type} parameter equals 'url'","type":"object","properties":{"formID":{"type":"integer"},"url":{"type":"object","properties":{"data":{"type":"string"},"info":{"type":"string"}}},"formInfo":{"type":"object","properties":{"utc_submission_timestamp":{"type":"string"},"approved":{"type":"boolean"},"utc_approved_timestamp":{"type":"string"},"aaid":{"type":"integer"}}},"userID":{"type":"string"}}},"EmployeeResponseSchema":{"description":"object returned for when getting/putting an employee into the system","type":"object","properties":{"id":{"type":"integer"},"first_name":{"type":"string"},"last_name":{"type":"string"},"username":{"type":"string"},"active":{"type":"boolean"},"email_address":{"type":"string"},"roles":{"type":"array","items":{"type":"object"}}}},"PrefillResponseSchema":{"description":"object of responses to questions being asked during employee creation","type":"object","properties":{"max_length":{"type":"string"},"question_number":{"type":"integer"},"required":{"type":"boolean"},"question_type":{"type":"string"},"special_format":{"type":"string"},"question_text":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}},"max_value":{"type":"string"},"prepopulated_value":{"type":"string"},"min_value":{"type":"string"},"forms":{"type":"array","items":{"type":"string"}},"help_text":{"type":"string"},"note_text":{"type":"string"},"example_text":{"type":"string"}}},"PostWebhookSchema":{"type":"object","properties":{"url":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}}}},"EmployeeCFUUIDIDRedirectPostBody":{"type":"object","properties":{"action":{"type":"string","description":"redirect destination.","enum":["employee-folder","division"]},"id":{"type":"integer","description":"id of redirect destination"}}},"EmployeeCreationPutBody":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"emailAddress":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"},"active":{"type":"boolean"}}},"EmployeeCreationPostBody":{"type":"object","properties":{"companyID":{"type":"integer"},"divisionID":{"type":"integer"},"firstName":{"type":"string"},"lastName":{"type":"string"},"emailAddress":{"type":"string"},"forms":{"type":"array","items":{"oneOf":[{"type":"string","enum":["D"]},{"type":"integer"}]}},"responses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"response":{"type":"string"}}}},"isTest":{"type":"boolean"}}},"WebhookReturnSchema":{"type":"object","properties":{"hash_key":{"type":"string"},"url":{"type":"string"},"id":{"type":"string"},"last_update":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}}}}},"examples":{"WebhookExampleSchema":{"value":{"hash_key":"02c201d1-1286-48b2-bbfb-89f82a42aca0","url":"https://your.secured-url.com","id":"9d0f3821-9dd5-4537-9f41-626c2fda1be4","last_update":"2018-07-24 20:24 +0000","topics":["5b6f94eb-0c53-45ef-99ab-a654f5d18223","a9b802e9-998e-4230-9d59-ecdcdb3d3fe1","e8883c8e-06f3-4626-a847-9a0630f90f33","599016c8-f6d0-422b-94c7-a9032bda0c35"]}}}},"security":[{"Authorization":[]}],"x-extensionDetection":true,"x-throwOnInvalidExtension":false,"x-validExtensions":"json"}