Version: 1.7.1

Update

Updates information of New Hire report records by Submission Id and Record Id.

PUT NewHireReport/Update

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
NHReports	object[]	Object to update New Hire reports.
RecordId	Guid	Unique Identifier of a record
Sequence	string	A unique number given by an inbound application to identify failed records. Size Range: ..60
ReportingToStateCd	string	State code of the New Hire Reporting State Size Range: 2
Employer	object	Employer details
BusinessId	Guid	Unique Identifier of the business
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
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	`Optional` Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Contact number of the business with area code 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: "ESTE", "PART", "CORP", "EORG", "SPRO"
KindOfEmployer	string	Identifies the kind of employer. Mandatory for W-2 and optional for 1099-MISC and 94X series. Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-MISC and 94X series. Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
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: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	State code of the employer/payer. 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"
ZipCd	string	Employer/Payer's zip code
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: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
AddEmployees	object[]	Employee details
Sequence	string	Employee sequence number. Size Range: ..60
SSN	string	Social Security Number (SSN). Size Range: ..9
FirstNm	string	Employee's First Name Size Range: ..15
MiddleNm	string	Employee's Middle Name Size Range: ..15
LastNm	string	Employee's Last Name Size Range: ..20
Suffix	string	Employee's Suffix. Size Range: ..3
Email	string	Employee's email address. Size Range: ..40
Fax	string	Employee's Fax number, if applicable. Size Range: 10
Phone	string	Employee's phone number including area code. Size Range: 10
USAddress	object	Object to identify the employee's US address
Address1	string	Employee's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employee's suite or apartment Size Range: ..35
City	string	Employer/Payer city. Size Range: ..27
State	string	State code of the employer/payer. 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"
ZipCd	string	Employer/Payer ZIP Code.
StateSpecifics	number	State specified information for New Hire Reporting
DOB	DateTime	Employee's Date of Birth
DtOfRemuneration	DateTime	Employee's Date of Remuneration
EmployeeUId	Guid	Unique Identifier of an Employee
HireType	string	Hire type of an employee. Applicable only for New Hires.
UpdateEmployees	object[]	Employee details
Sequence	string	Employer sequence number. Size Range: ..60
SSN	string	Social Security Number (SSN). Size Range: ..9
FirstNm	string	Employee's First Name Size Range: ..15
MiddleNm	string	Employee's Middle Name Size Range: ..15
LastNm	string	Employee's Last Name Size Range: ..20
Suffix	string	Employee's Suffix. Size Range: ..3
Email	string	Employee's email address. Size Range: ..40
Fax	string	Employee's Fax number, if applicable. Size Range: 10
Phone	string	Employee's phone number including area code. Size Range: 10
USAddress	object	Object to identify the employee's US address
Address1	string	Employee's US address (street address or post office box of that locality). Size Range: ..35
Address2	string	`Optional` The suite, apartment, number of the employer/payer, if applicable. Size Range: ..35
City	string	Employer/Payer city. Size Range: ..27
State	string	State code of the employer/payer. 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"
ZipCd	string	Employer/Payer ZIP Code.
StateSpecifics	number	State specified information for New Hire Reporting
DOB	DateTime	Employee's Date of Birth
DtOfRemuneration	DateTime	Employee's Date of Remuneration
EmployeeUId	Guid	Unique Identifier of an Employee
HireType	string	Hire type of an employee. Applicable only for New Hires.
DeleteEmployees	Guid[]	Employee's Unique Identifier

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.
NHReports	object	Pulls the New Hire report records with Success and Error statuses.
SuccessRecords	object[]	It will show the detailed information about the success status of New Hire Report 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.
EmployeeRecords	string	Return status details like Created, Transmitted, Accepted, Rejected.
Sequence	string	A unique number given by an inbound application to identify failed records.
EmployeeUId	Guid	Unique identifier of an Employee.
Status	string	Returns the status of the Employee details.
CreatedTs	DateTime	Date and time of return created.
UpdatedTs	DateTime	Date and time of return updated.
ErrorRecords	object[]	It will show the detailed information about the error status of New Hire Report Records.
Sequence	string	A unique number given by an inbound application to identify failed records.
RecordId	Guid	Unique identifier of a record.
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.
EmployeeErrorRecords	object[]	Return status details like Created, Transmitted, Accepted, Rejected.
Sequence	string	A unique number given by an inbound application to identify failed records.
EmployeeUId	Guid	Client Record Identifier.
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.
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.

Request JSON

{
 "NHReports": [
   {
     "RecordId": "53a64158-6333-44ef-8e26-1cd20ba79f78",
     "Sequence": null,
     "ReportingToStateCd": "SC",
     "Employer": {
       "BusinessId": null,
       "BusinessNm": "Eastman Kodak Company",
       "TradeNm": null,
       "IsEIN": true,
       "EINorSSN": "003333333",
       "Email": "john@gmail.com",
       "ContactNm": "John",
       "Phone": "1234567890",
       "PhoneExtn": "12345",
       "Fax": "1234567890",
       "BusinessType": null,
       "SigningAuthority": null,
       "KindOfEmployer": null,
       "KindOfPayer": null,
       "IsBusinessTerminated": false,
       "IsForeign": false,
       "USAddress": {
         "Address1": "1751 Kinsey Rd",
         "Address2": "Main St",
         "City": "Dothan",
         "State": "AL",
         "ZipCd": "36303"
       },
       "ForeignAddress": {
         "Address1": null,
         "Address2": null,
         "City": null,
         "ProvinceOrStateNm": null,
         "Country": null,
         "PostalCd": null
       }
     },
     "AddEmployees": [
       {
         "Sequence": "3",
         "SSN": "393848038",
         "FirstNm": "John",
         "MiddleNm": "F",
         "LastNm": "Kennedy",
         "Suffix": "Sr",
         "Email": "john@gmail.com",
         "Fax": "1234567890",
         "Phone": "1234567890",
         "USAddress": {
           "Address1": "1751 Kinsey Rd",
           "Address2": "Main St",
           "City": "Dothan",
           "State": "AL",
           "ZipCd": "36303"
         },
         "StateSpecifics": {
           "DOB": "1990-07-01T00:00:00",
           "DtOfRemuneration": "2019-08-01T00:00:00"
         },
         "EmployeeUId": null,
         "HireType": "NEWHIRE"
       }
     ],
     "UpdateEmployees": [
       {
         "Sequence": "1",
         "SSN": "393848035",
         "FirstNm": "John",
         "MiddleNm": "F",
         "LastNm": "Kennedy",
         "Suffix": "Jr",
         "Email": "john@gmail.com",
         "Fax": "1234567899",
         "Phone": "1234567899",
         "USAddress": {
           "Address1": "12 main st",
           "Address2": null,
           "City": "Rock HIll",
           "State": "SC",
           "ZipCd": "29730"
         },
         "StateSpecifics": {
           "DOB": "1991-07-31T00:00:00",
           "DtOfRemuneration": "2019-07-10T00:00:00"
         },
         "EmployeeUId": "bc88cd09-f537-4395-b54f-ccee2d4d6997",
         "HireType": "NEWHIRE"
       }
     ],
     "DeleteEmployees": [
       "44fd0c52-0216-4731-b088-f8faa84e0de5"
     ]
   }
 ],
 "SubmissionId": "931f8057-fe2e-4dcd-babd-5527ef098a6c"
}

Response JSON

{
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "SubmissionId": "931f8057-fe2e-4dcd-babd-5527ef098a6c",
 "NHRecords": {
   "SuccessRecords": [
     {
       "Sequence": null,
       "RecordId": "53a64158-6333-44ef-8e26-1cd20ba79f78",
       "RecordStatus": "Created",
       "EmployeeRecords": [
         {
           "Sequence": "3",
           "EmployeeUId": "0be8f3cf-b78c-4f5b-9ee6-e4a5089d2f4a",
           "Status": "ADDED"
         },
         {
           "Sequence": "1",
           "EmployeeUId": "bc88cd09-f537-4395-b54f-ccee2d4d6997",
           "Status": "UPDATED"
         },
         {
           "Sequence": null,
           "EmployeeUId": "44fd0c52-0216-4731-b088-f8faa84e0de5",
           "Status": "DELETED"
         }
       ],
       "CreatedTs": "2019-08-06 22:02:48 -04:00",
       "UpdatedTs": "2019-08-06 22:06:07 -04:00"
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}

Extend your software with TaxBandits IRS E-file API Integration