Skip to main content
Version: 1.7.3

Update

Update

Use this endpoint to update the information on existing new hire reports that are already created for the business.

Note:

You cannot update a report once it has been transmitted.

PUT NewHire/Employee/Update
Run in Postman

Request Body

FieldTypeDescription
SubmissionIdGuidUnique identifier created by TaxBandits for each submission. Not required when you are creating a return.
ReturnHeaderobjectIdentifies the supporting details of New Hire Form
BusinessobjectThe details of the business you’re filing for.
BusinessIdGuidOptional 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.
BusinessNmstringName of the business
Size Range: ..75
PayerRefstringOptional An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API.
Size Range: ..50
TradeNmstringOptional Name under which the business operates
Size Range: ..75
IsEINBooleanWhen true, identifies the business with an EIN.
EINorSSNstringWhen IsEIN is true, use Employer Identification Number (EIN). When IsEIN is false, use Social Security Number (SSN)
Size Range: 9-11
EmailstringEmail address of the Business
Size Range: ..100
IsForeignBooleanWhen true, identifies the business address with a foreign address.
USAddressobjectif IsForeign is false, pass US address of the business
Address1stringEmployer/Payer's US address (street or post office box of that locality)
Size Range: ..46
Address2stringOptional Employer/Payer's suite or apartment
Size Range: ..46
CitystringEmployer/Payer's city
Size Range: ..50
StatestringEmployer/Payer's state code. Refer Static values.
Size Range: 2
Allowed values

"AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "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", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"

ZipCdstringEmployer/Payer's zip code
Size Range: 5..10
ForeignAddressobjectIf IsForeign is true, pass foreign address of the business
Address1stringEmployer/Payer's foreign address (street address or post office box of that locality)
Size Range: ..50
Address2stringOptional Employer/Payer's suite or apartment
Size Range: ..50
CitystringEmployer/Payer's city
Size Range: ..50
ProvinceOrStateNmstringEmployer/Payer's province or state name
Size Range: ..50
CountrystringEmployer/Payer's country
Size Range: 2
Allowed values

"AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"

PostalCdstringEmployer/Payer's postal code
Size Range: ..16
ReturnDataobjectIdentifies the employee details
EmployeeDetailsobject[]Data of the newhire employee
SequenceIdstringA unique number given by an inbound application to identify records.
Size Range: ..10
EmployeeIdstringOptional TaxBandits generates a unique ID for each employee after the return is created and returned in the Response. You can use this id for your future reference to update.
EmpRefstringOptional A unique identifier for each employee completing their information. This identifier can be used in future references of the payee in the API.
Size Range: ..50
SSNstringSocial Security Number of the employee
Size Range: 9-11
FirstNmstringFirst Name of the Employee
Size Range: ..20
MiddleNmstringMiddle Name of the Employee
Size Range: ..20
LastNmstringLast Name of the Employee
Size Range: ..20
SuffixstringSuffix of the employee
Allowed values

"Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"

IsForeignBooleanWhen true, identify the employee address with a foreign address.
USAddressobjectIf IsForeign is false, pass the US address of the employee
Address1stringEmployee's US address (street address or post office box of that locality)
Size Range: ..46
Address2stringOptional Employee's suite or apartment
Size Range: ..46
CitystringEmployee's city
Size Range: ..50
StatestringEmployee's state code. Refer Static values.
Size Range: 2
Allowed values

"AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "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", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"

ZipCdstringEmployee's zip code
Size Range: 5..10
ForeignAddressobjectIf IsForeign is true, pass the foreign address of the employee
Address1stringEmployee's foreign address (street address or post office box of that locality)
Size Range: ..50
Address2stringOptional Employee's suite or apartment
Size Range: ..50
CitystringEmployee's city.
Size Range: ..50
ProvinceOrStateNmstringEmployee's Province or State Name.
Size Range: ..50
CountrystringEmployee's country code. Refer Static values.
Size Range: 2
Allowed values

"AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"

PostalCdstringEmployee's Postal Code.
Size Range: ..16
DOBstringEmployee's date of birth. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY
Example: 01/25/2025 or 01-25-2025
HireDatestringEmployee's hire date. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY
Example: 01/25/2025 or 01-25-2025
ReportingStatestringReporting state. Refer Static values.
Size Range: 2
Allowed values

"SC"

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
BusinessIdGuidUnique Identifier of the business
PayerRefstringUnique identifier of the payer.
SuccessRecordsobject[]It will show the detailed information about the success status of New Hire Form Records.
SequenceIdstringA unique number given by an inbound application to identify failed records.
RecordIdGuidUnique identifier of a record.
EmployeeIdGuidUnique Identifier of the business
EmpRefstringUnique identifier of the payer.
StatusstringReturns the status of the records.
StatusTsstringReturns date and time of return created.
InfostringReturns information about the New Hire filing service.
Errorsobject[]Shows error information of state returns of New Hire form
IdstringReturns the validation error Id.
NamestringName of the validation error.
MessagestringDescription of the validation error.
ErrorRecordsobject[]It will show the detailed information about the error status of NewHire Form Records.
SequenceIdstringAn unique reference ID for the submission that can be used to identify a particular record. The Sequence ID will be returned in the Response for your reference.
Errorsobject[]Shows detailed error information
IdstringReturns the validation error Id
NamestringName of the validation error
MessagestringDescription of the validation error
Errorsobject[]Shows detailed error information
IdstringReturns the validation error Id
NamestringName of the validation error
MessagestringDescription of the validation error

Request JSON​

{
    "SubmissionId": "01993c59-8621-77cb-8e74-f044c5d6ed70",
    "ReturnHeader": {
        "Business": {
            "BusinessId": "7d383c5a-f4db-4ac6-b10c-adc16584096e"
                    }
    },
    "ReturnData": {
        "EmployeeDetails": [
            {
                "SequenceId": "1",
                "RecordId": "01993c59-89bc-74da-87e1-82d3b74545a8",
                "EmployeeId": "11dc23f9-f59b-4fd8-be62-5fb8174cf2a4",
                "EmpRef": "2344",
                "SSN": "001-45-6924",
                "FirstNm": "Henry",
                "MiddleNm": "L",
                "LastNm": "Thomas",
                "Suffix": null,
                "IsForeign": false,
                "USAddress": {
                    "Address1": "12 Main st",
                    "Address2": "CC avenue",
                    "City": "Rock Hill",
                    "ZipCd": "29730",
                    "State": "SC",
                    "Country": "US"
                },
                "ForeignAddress": null,
                "DOB": "11/11/2002",
                "HireDate": "07/21/2025",
                "ReportingState": "SC"
            }
        ]
    }
}

Response JSON​

Success Response - This is a sample response for successful API requests.

{
  "StatusCode": "200",
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "01993cd0-02f9-7788-bb2a-f3410a5a1fe7",
  "BusinessId": "07e6d7d9-5463-43d2-a272-14dc563cb5e0",
  "SuccessRecords": [
      {
          "SequenceId": "1",
          "RecordId": "01993cd0-05d6-730b-bcc9-484a7e92d42e",
          "EmployeeId": "b3a91620-d26c-421e-95c6-1176522f105a",
          "EmpRef": "2344",
          "ReportingState": "SC",
          "Status": "CREATED",
          "StatusTs": "2025-09-12 03:25:31 -04:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": null,
  "Errors": null
}