Update
Updates the information on Form 940SCHRs by Submission Id and Record Id.
PUT Form940SchR/Update 
Request Body
| Field | Type | Description |
|---|---|---|
| SubmissionId | Guid | Unique identifier of a submission. |
| Form940SchRRecords | object[] | Collection of objects to update Form 940SCHR and aggregate Form 940 records. |
| Sequence | string | A unique number given by an inbound application to identify failed records. Size Range: ..10 |
| ReturnHeader | object | Identifies the supporting details of Form940SCHR |
| ReturnType | string | Type of the return to be filed. Enter values like. Allowed values: "FORM940SCHR" |
| MoreClients | Boolean | When MoreClients is true, allows submission for more than 1000 clients . When MoreClients is false, allows a maximum of 1000 clients in one submission. Required only for Form 941SCHR/940SCHR. |
| TaxYr | string | Tax year for which Form 940 SCH R needs to be filed.Allowed values |
| Business | object | Object to identify the Business details. |
| BusinessId | Guid | Use the unique Business ID (Generated by TaxBandits), you received in the response of the Business CREATE Endpoint. If you have do not have a Business ID, ignore the field. By giving the Business ID, you do not have to provide all the business information again. |
| BusinessNm | string | Name of the business Size Range: ..75 |
| TradeNm | string | Optional Name under which the business operates Size Range: ..75 |
| IsEIN | Boolean | When true, identifies the business with an EIN. |
| EINorSSN | string | When IsEIN is true, use Employer Identification Number (EIN). When IsEIN is false, use Social Security Number (SSN). Size Range: 9-11 |
| string | Email address of the business Size Range: ..100 | |
| ContactNm | string | OptionalName of the person who can be contacted by the IRS Size Range: ..27 |
| Phone | string | Contact number of the business. Size Range: 10 |
| PhoneExtn | string | Optional Extension of the business phone number Size Range: ..5 |
| Fax | string | Optional Fax number of the Business Size Range: 10 |
| BusinessType | string | Type of business. Optional for W-2/1099 and mandatory for 94X series. Size Range: ..4 Allowed values |
| SigningAuthority | object | Details of the person who is authorized to sign the return. |
| Name | string | Name of the signing authority. Size Range: ..35 |
| Phone | string | Phone number of the signing authority. Size Range: 10 |
| BusinessMemberType | string | Business title of the signing authority. Size Range: 5..29 Allowed values |
| KindOfEmployer | string | Identifies the kind of employer. Mandatory for W-2 and optional for 1099-MISC and 94X series.Allowed values |
| KindOfPayer | string | Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-MISC and 94X series.Allowed values |
| IsBusinessTerminated | Boolean | When true, identifies the business as terminated. |
| IsForeign | Boolean | When true, identifies the business address with a foreign address. |
| USAddress | object | If IsForeign is false, pass US address of the business |
| Address1 | string | Employer/Payer's US address (street address or post office box of that locality) Size Range: ..46 |
| Address2 | string | Optional Employer/Payer's suite or apartment Size Range: ..46 |
| City | string | Employer/Payer's city Size Range: ..50 |
| State | string | State code of the employer/payer. Refer Static values. Size Range: 2 Allowed values |
| ZipCd | string | Employer/Payer's zip code. Size Range: 5..10 |
| ForeignAddress | object | If IsForeign is true, pass foreign address of the business |
| Address1 | string | Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..50 |
| Address2 | string | Optional Employer/Payer's suite or apartment. Size Range: ..50 |
| City | string | Employer/Payer's city. Size Range: ..50 |
| ProvinceOrStateNm | string | Employer/Payer's province or state name. Size Range: ..50 |
| Country | string | Employer/Payer country code. Refer Static values. Size Range: 2 Allowed values |
| PostalCd | string | Employer/Payer's postal code. Size Range: ..16 |
| IsThirdPartyDesignee | Boolean | When true, your third-party designee is allowed to discuss the return with the IRS |
| ThirdPartyDesignee | object | Third Party Designee Details |
| Name | string | Third Party Designee's name. |
| Phone | string | Third Party Designee's phone number. |
| PIN | string | A 5 digit PIN (Should not contain all zeroes) used when communicating to the IRS. |
| SignatureDetails | object | Identifies the signature type used in Form 940 |
| SignatureType | string | Type of signature used to sign Form 940 SCHR Allowed values |
| OnlineSignaturePIN | object | A 10-digit signature PIN to become an IRS authorized signer. |
| PIN | string | Sign using a 10 digit PIN received from the IRS. Size Range: 10 |
| ReportingAgentPIN | object | A 5-digit number assigned by the IRS |
| PIN | string | Sign using a 5 digit PIN received from the IRS. Size Range: 5 |
| Form8453EMP | object | An alternate option to sign the return using Form 8453 EMP when there is no PIN |
| ReturnData | object | Identifies the Form 940SCHR and Aggregate Form 940 data. |
| Form940MainFilerData | object | Form 940 Details of the CPEO or the sec. 3504 Agent's employees for Schedule R |
| IsSuccessorEmployer | Boolean | Are you a successor employer? (Yes / No) |
| IsAmended | Boolean | Is this an Amended return (Yes / No) |
| IsPymtsMadeToEmployees | Boolean | Have you made any payments to employees during the filing tax year? (Yes / No) |
| IsBusinessClosed | Boolean | Is this your final return? (Business closed or stopped paying wages) (Yes / No) |
| FilerType | string | Section 3504 Agent / CPEOAllowed values |
| TotTaxableWagesAmt | number | Total taxable FUTA wages amount Size Range: 0-9999999999999.99 |
| FUTAAdjAmt | number | FUTA Adjustment amount Size Range: 0-9999999999999.99 |
| TotCrdtRedAmt | number | Total credit reduction amount. Enter the total from Schedule A (Form 940) Size Range: 0-9999999999999.99 |
| FUTATaxAfterAdjAmt | number | Total FUTA tax after adjustments amount Size Range: 0-9999999999999.99 |
| TotDepositAmt | number | FUTA tax deposited for the year, including any overpayment applied from a prior year Size Range: 0-9999999999999.99 |
| FUTAStates | object[] | Schedule A (Form 940), Multi-State Employer and Credit Reduction Information |
| StateCd | string | State code of the employer/client. Size Range: 2 Allowed values |
| TotTaxableFUTAwagesAmt | number | Total taxable FUTA wages amount of the state Size Range: 0-99999999999999.99 |
| CreditReductionRt | number | Credit Reduction Rate of the state Size Range: 0-99999999999999.99 |
| CreditReductionAmt | number | Credit Reduction amount of the state. This will be equal to the Total taxable FUTA wages amount multiplied with the Credit Reduction Rate. (Round of the amount upto 2 digits after decimal point) Size Range: 0-99999999999999.99 |
| AddForm940ClientDetails | object[] | Add a Collection of Form 940 Details of each client for Schedule R. |
| CSeqId | string | A unique sequence number of a client. Size Range: ..10 |
| ClientEIN | string | Gets the client’s Employer identification number (EIN). Schedule R Column a. Size Range: 9 |
| StateCd | string | State code of the Client. Schedule R Column b. Size Range: 2 Allowed values |
| WagesTypeCd | string | Gets the code type of wages,tips, and other compensation (CPEO Use Only). Schedule R Column c. Allowed values |
| TotTaxableWagesAmt | number | Get the total taxable FUTA wages amount. Schedule R Column d. Size Range: 0-99999999999999.99 |
| FUTAAdjAmt | number | Get the total adjustments to FUTA tax. Schedule R Column e. Size Range: 0-99999999999999.99 |
| TotCrdtRedAmt | number | Get the total credit reduction amount. Schedule R Column f. Size Range: 0-99999999999999.99 |
| FUTATaxAfterAdjAmt | number | Get the total FUTA tax after adjustment amount. Schedule R Column g. Size Range: 0-99999999999999.99 |
| TotDepositAmt | number | Get the total FUTA tax deposit amount. Schedule R Column h. Size Range: 0-99999999999999.99 |
| CRecordId | Guid | Unique identifier of a client record. |
| UpdateForm940ClientDetails | object[] | Update a Collection of Form 940 Details of each client for Schedule R. |
| CSeqId | string | A unique sequence number of a client. Size Range: ..10 |
| ClientEIN | string | Gets the client’s Employer identification number (EIN). Schedule R Column a. Size Range: 9 |
| StateCd | string | State code of the Client. Schedule R Column b. Size Range: 2 Allowed values |
| WagesTypeCd | string | Gets the code type of wages,tips, and other compensation (CPEO Use Only). Schedule R Column c. Allowed values |
| TotTaxableWagesAmt | number | Get the total taxable FUTA wages amount. Schedule R Column d. Size Range: 0-99999999999999.99 |
| FUTAAdjAmt | number | Get the total adjustments to FUTA tax. Schedule R Column e. Size Range: 0-99999999999999.99 |
| TotCrdtRedAmt | number | Get the total credit reduction amount. Schedule R Column f. Size Range: 0-99999999999999.99 |
| FUTATaxAfterAdjAmt | number | Get the total FUTA tax after adjustment amount. Schedule R Column g. Size Range: 0-99999999999999.99 |
| TotDepositAmt | number | Get the total FUTA tax deposit amount. Schedule R Column h. Size Range: 0-99999999999999.99 |
| CRecordId | Guid | Unique identifier of a client record. |
| DeleteForm940ClientDetails | object[] | Delete a Collection of Form 940 Details of each client for Schedule R. |
| ClientRecordId | Guid | Client Record Identifier |
| Form940Total | object | Aggregate Form 940 (Totals of Clients + the main filer). For Form 940 |
| IsMultiState | Boolean | When true, identifies the employer as a multi-state employer. |
| WagesAmt | number | Gets the amount of the total payments made to all employees. Line 3. Size Range: 0-99999999999999.99 |
| ExemptWagesAmt | number | Gets the amount of the payments exempt from FUTA tax. Line 4. Size Range: 0-99999999999999.99 |
| IsFringeBenfs | Boolean | When true, identifies the payments exempt from FUTA tax has Fringe Benefits. |
| IsGrpTermLifeIns | Boolean | When true, identifies the payments exempt from FUTA tax has Group-term life insurance. |
| IsRetrmntOrPension | Boolean | When true, identifies the payments exempt from FUTA tax has Retirement/Pension. |
| IsDepCare | Boolean | When true, identifies the payments exempt from FUTA tax has Dependent care. |
| IsOtherExempt | Boolean | When true, identifies the payments exempt from FUTA tax has other Exempt. |
| WagesOverLmtAmt | number | Gets the total amount of the payments made to each employee in excess of $7,000. Line 5 Size Range: 0-99999999999999.99 |
| TotExemptWagesAmt | number | Gets the subtotal amount by adding the amounts on Line 4 and 5 on Line 6. Size Range: 0-99999999999999.99 |
| TotTaxableWagesAmt | number | Gets the total taxable FUTA wages by subtracting the amount on line 6 from line 3 on line 7. Size Range: 0-99999999999999.99 |
| FUTATaxBeforeAdjAmt | number | Gets the total FUTA tax before adjustments by multiplying line 7 by 0.006 on line 8. Size Range: 0-99999999999999.99 |
| MaxCreditAmt | number | Gets the amount by multiplying line 7 by 0.054 on line 9 if all taxable FUTA wages paid were excluded from state unemployment tax. Line 9. Size Range: 0-99999999999999.99 |
| FUTAAdjAmt | number | Gets some of the taxable FUTA Wages that were excluded from State Unemployment Tax or the late payments that were made for state unemployment tax. Size Range: 0-99999999999999.99 |
| TotCrdtRedAmt | number | Gets the FUTA taxable wages that were also subject to state unemployment taxes in any states that are subject to credit recuction. Line 11. Size Range: 0-99999999999999.99 |
| FUTATaxAfterAdjAmt | number | Gets the total FUTA tax after adjustments amount by adding the amounts on Lines 8, 9, 10, 11. Line 12. Size Range: 0-99999999999999.99 |
| TotDepositAmt | number | Gets the amount of FUTA tax deposited for the year, including any overpayment applied from a prior year. Line 13. Size Range: 0-99999999999999.99 |
| FirstQtrTaxLiabilityAmt | number | Gets the FUTA Tax Liability amount for 1st quarter (January 1 – March 31). Line 16a. Size Range: 0-99999999999999.99 |
| secondQtrTaxLiabilityAmt | number | Gets the FUTA Tax Liability amount for 2nd quarter (April 1 – June 30). Line 16b. Size Range: 0-99999999999999.99 |
| ThirdQtrTaxLiabilityAmt | number | Gets the FUTA Tax Liability amount for 3rd quarter (July 1 – September 30). Line 16c. Size Range: 0-99999999999999.99 |
| FourthQtrTaxLiabilityAmt | number | Gets the FUTA Tax Liability amount for 4th quarter (October 1 – December 31). Line 16d. Size Range: 0-99999999999999.99 |
| TotTaxLiabilityAmt | number | Gets the total FUTA tax liability amount for the year. Line 17. Size Range: 0-99999999999999.99 |
| BalanceDueAmt | number | Gets the difference amount of the balance due if line 12 is more than line 13. Line 14 Size Range: 0-99999999999999.99 |
| OverPaidAmt | number | Gets the difference overpayment amount if line 13 is more than line 12. Line 15. Size Range: 0-99999999999999.99 |
| OverPaymentRecoveryType | string | Gets the overpayment recovery type. Whether to have the IRS refund the excess amount or apply it to next return. Check only one box on line 15.Allowed values |
| IRSPaymentType | string | Payment type to make payments to the IRS. Choose from EFW, EFTPS, Check or Money OrderAllowed values |
| IRSPayment | object | Identifies the details of Electronic Funds Withdrawal (EFW) if paying the balance due along with the return |
| BankRoutingNum | string | Bank Routing Number of EFW payment Size Range: 9 |
| AccountType | string | Account Type (Checking or Saving) of EFW payment |
| BankAccountNum | string | Bank Account Number of EFW payment Size Range: ..17 |
| Phone | string | Phone of EFW payment Size Range: 10 |
| FinalPayRoll | object | Identifies name and address of the Record Keeper |
| PersonNm | string | Name of the Record Keeper Size Range: ..40 |
| IsForeign | Boolean | When true, identifies the business address with a foreign address. |
| USAddress | object | if IsForeign is false, pass US address of the business |
| Address1 | string | Employer/Payer's US address (street address or post office box of that locality) Size Range: ..46 |
| Address2 | string | Optional Employer/Payer's suite or apartment Size Range: ..46 |
| City | string | Employer/Payer's city Size Range: ..50 |
| State | string | State code of the employer/payer. Refer Static values. Size Range: 2 Allowed values |
| ZipCd | string | Employer/Payer's zip code. Size Range: 5..10 |
| ForeignAddress | object | if IsForeign is true, pass foreign address of the business. |
| Address1 | string | Employer/Payer's foreign address (street address or post office box of that locality). Size Range: ..50 |
| Address2 | string | Optional Employer/Payer's suite or apartment Size Range: ..50 |
| City | string | Employer/Payer's city Size Range: ..50 |
| ProvinceOrStateNm | string | Employer/Payer's province or state name. Size Range: ..50 |
| Country | string | Employer/Payer country code. Refer Static values. Size Range: 2 Allowed values |
| PostalCd | string | Employer/Payer's postal code Size Range: ..16 |
| ScheduleA | object[] | Schedule A (Form 940), Multi-State Employer and Credit Reduction Information |
| StateCd | string | State code of the employer/client. Size Range: 2 Allowed values |
| TotTaxableFUTAwagesAmt | number | Total taxable FUTA wages amount of the state Size Range: 0-99999999999999.99 |
| CreditReductionRt | number | Credit Reduction Rate of the state Size Range: 0-99999999999999.99 |
| CreditReductionAmt | number | Credit Reduction amount of the state. This will be equal to the Total taxable FUTA wages amount multiplied with the Credit Reduction Rate. (Round of the amount upto 2 digits after decimal point) Size Range: 0-99999999999999.99 |
| RecordId | Guid | Unique identifier of a record. |
Request JSON
{
"SubmissionId": "e6e465db-f293-44e6-b659-3e528ea0cec7",
"Form940SchRRecords": [
{
"Sequence": null,
"ReturnHeader": {
"ReturnType": "FORM940SCHR",
"MoreClients": false,
"TaxYr": "2022",
"Business": {
"BusinessId": null,
"BusinessNm": "Snowdaze LLC",
"TradeNm": null,
"IsEIN": true,
"EINorSSN": "107820402",
"Email": "sample@bodeem.com",
"ContactNm": "John",
"Phone": "1234567890",
"PhoneExtn": null,
"Fax": "1234567890",
"BusinessType": "ESTE",
"SigningAuthority": {
"Name": "John",
"Phone": "1234567890",
"BusinessMemberType": "ADMINISTRATOR"
},
"KindOfEmployer": null,
"KindOfPayer": null,
"IsBusinessTerminated": false,
"IsForeign": false,
"USAddress": {
"Address1": "1751 Kinsey Rd",
"Address2": "Main St",
"City": "Dothan",
"State": "SC",
"ZipCd": "36303"
},
"ForeignAddress": {
"Address1": null,
"Address2": null,
"City": null,
"ProvinceOrStateNm": null,
"Country": null,
"PostalCd": null
}
},
"IsThirdPartyDesignee": false,
"ThirdPartyDesignee": {
"Name": null,
"Phone": null,
"PIN": null
},
"SignatureDetails": {
"SignatureType": "ONLINE_SIGN_PIN",
"OnlineSignaturePIN": {
"PIN": "1234567891"
},
"ReportingAgentPIN": {
"PIN": null
},
"Form8453EMP": null
}
},
"ReturnData": {
"Form940MainFilerData": {
"IsSuccessorEmployer": false,
"IsAmended": false,
"IsPymtsMadeToEmployees": true,
"IsBusinessClosed": false,
"FilerType": "CPEO",
"TotTaxableWagesAmt": 7000,
"FUTAAdjAmt": 58,
"TotCrdtRedAmt": 210,
"FUTATaxAfterAdjAmt": 310,
"TotDepositAmt": 50,
"FUTAStates": [
{
"StateCd": "VI",
"TotTaxableFUTAwagesAmt": 7000,
"CreditReductionRt": 0.03,
"CreditReductionAmt": 210
}
]
},
"AddForm940ClientDetails": null,
"UpdateForm940ClientDetails": [
{
"CSeqId": "1",
"ClientEIN": "008774111",
"StateCd": "VI",
"WagesTypeCd": "a",
"TotTaxableWagesAmt": 7000,
"FUTAAdjAmt": 58,
"TotCrdtRedAmt": 210,
"FUTATaxAfterAdjAmt": 310,
"TotDepositAmt": 50,
"CRecordId": "3982d093-1838-404b-8b0c-9bc1491c9701"
}
],
"DeleteForm940ClientDetails": null,
"Form940Total": {
"IsMultiState": false,
"WagesAmt": 27000,
"ExemptWagesAmt": 2000,
"IsFringeBenfs": true,
"IsGrpTermLifeIns": false,
"IsRetrmntOrPension": false,
"IsDepCare": false,
"IsOtherExempt": false,
"WagesOverLmtAmt": 4000,
"TotExemptWagesAmt": 6000,
"TotTaxableWagesAmt": 21000,
"FUTATaxBeforeAdjAmt": 126,
"MaxCreditAmt": 0,
"FUTAAdjAmt": 174,
"TotCrdtRedAmt": 630,
"FUTATaxAfterAdjAmt": 930,
"TotDepositAmt": 150,
"FirstQtrTaxLiabilityAmt": 300,
"secondQtrTaxLiabilityAmt": 200,
"ThirdQtrTaxLiabilityAmt": 430,
"FourthQtrTaxLiabilityAmt": 0,
"TotTaxLiabilityAmt": 930,
"BalanceDueAmt": 780,
"OverPaidAmt": 0,
"OverPaymentRecoveryType": null
},
"IRSPaymentType": "EFTPS",
"IRSPayment": {
"BankRoutingNum": null,
"AccountType": null,
"BankAccountNum": null,
"Phone": null
},
"FinalPayRoll": null,
"ScheduleA": [
{
"StateCd": "VI",
"TotTaxableFUTAwagesAmt": 21000,
"CreditReductionRt": 0.03,
"CreditReductionAmt": 630
}
]
},
"RecordId": "b3b9fc3c-6577-418f-bc5e-895b9478ce25"
}
]
}
Response Body
| Field | Type | Description |
|---|---|---|
| StatusCode | number | Returns the HTTP status codes like 200,300 etc. |
| StatusName | string | Name of the status code. |
| StatusMessage | string | Detailed status message. |
| SubmissionId | Guid | Unique identifier of a submission |
| Form940SchRRecords | object | Pulls the Form 940SCHR records with Success and Error statuses |
| SuccessRecords | object[] | It will show the detailed information about the success status of Form 940 Records |
| Sequence | string | A unique number given by an inbound application to identify failed records. |
| RecordId | Guid | Unique identifier of a record. |
| RecordStatus | string | Returns the status of the records. |
| CreatedTs | string | Date and time of return created. |
| UpdatedTs | string | Date and time of return updated. |
| ClientSuccessRecords | object[] | Client Success Status. |
| CSeqId | string | This identifies the sequence on the record sent in the payload. When errors occur we will send the errors attached to particular sequence. |
| CRecordId | string | Client Record Identifier |
| RecordStatus | string | Return status details like Processing, Created, Accepted, Rejected. |
| CreatedTs | string | Return created date and time |
| UpdatedTs | string | Return updated date and time |
| ErrorRecords | object[] | It will show the detailed information about the error status of Form 940 Records |
| RecordId | Guid | Unique identifier of a record |
| Sequence | string | A unique number given by an inbound application to identify failed records. |
| Errors | object[] | Shows detailed error information. |
| Code | string | Returns the validation error code. |
| Name | string | Name of the validation error. |
| Message | string | Description of the validation error. |
| Type | string | Type of validation error. |
| ClientErrorRecords | object[] | Client Error Status. |
| CSeqId | object[] | This identifies the sequence on the record sent in the payload. When errors occur we will send the errors attached to particular sequence. |
| CRecordId | object[] | Client Record Identifier |
| Errors | object[] | It will show the detailed information about the error. |
| Code | string | It will return the validation error code. |
| Name | string | It will return the name of the validation error. |
| Message | string | It will return the detailed message of the validation error. |
| Type | string | It will show the type of an error. |
| Errors | object[] | Shows detailed error information. |
| Code | string | Returns the validation error code. |
| Name | string | Name of the validation error. |
| Message | string | Description of the validation error. |
| Type | string | Type of validation error. |
Response JSON
Success Response - This is a sample response for successful API requests.
{
"StatusCode": 200,
"StatusName": "Ok",
"StatusMessage": "Successful API call",
"SubmissionId": "e6e465db-f293-44e6-b659-3e528ea0cec7",
"Form940SchRRecords": {
"SuccessRecords": [
{
"Sequence": "01",
"RecordId": "b3b9fc3c-6577-418f-bc5e-895b9478ce25",
"RecordStatus": "Created",
"CreatedTs": "2021-03-29 09:54:08 -04:00",
"UpdatedTs": "2021-03-29 09:59:34 -04:00",
"ClientSuccessRecords": [
{
"CSeqId": "1",
"CRecordId": "3982d093-1838-404b-8b0c-9bc1491c9701",
"RecordStatus": "Updated",
"CreatedTs": "2021-03-29 09:54:09 -04:00",
"UpdatedTs": "2021-03-29 09:59:34 -04:00"
}
]
}
],
"ErrorRecords": null
},
"Errors": null
}