Version: 1.7.3

Create

Use this endpoint to generate a new hire report for your employees. You must generate a separate report for each employee and can add multiple states in a single report.

Employer Details: Provide the BusinessId or PayerRef of the business you’re creating the report for.
Employee Details: Include the newly hired employee’s full name, Social Security Number (SSN), DOB and address.
Hire Date: Specify the employee’s hire date, as most states require reporting within a certain number of days from hire.
State Reporting: Indicate the state(s) where the report should be submitted.

POST NewHire/Employee/Create

Run in Postman

Request Body

Field	Type	Description
ReturnHeader	object	Identifies the supporting details of New Hire Form
Business	object	The details of the business you’re filing for.
BusinessNm	string	Name of the business Size Range: ..75
PayerRef	string	Optional 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
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
Email	string	Email address of the Business Size Range: ..100
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 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	Employer/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"
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'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"
PostalCd	string	Employer/Payer's postal code Size Range: ..16
ReturnData	object	Identifies the employee details
EmployeeDetails	object[]	Data of the newhire employee
SequenceId	string	A unique number given by an inbound application to identify records. Size Range: ..10
EmployeeId	string	Optional 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.
EmpRef	string	Optional 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
SSN	string	Social Security Number of the employee Size Range: 9-11
FirstNm	string	First Name of the Employee Size Range: ..20
MiddleNm	string	Middle Name of the Employee Size Range: ..20
LastNm	string	Last Name of the Employee Size Range: ..20
Suffix	string	Suffix of the employee Allowed values "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
IsForeign	Boolean	When true, identify the employee address with a foreign address.
USAddress	object	If IsForeign is false, pass the US address of the employee
Address1	string	Employee's US address (street address or post office box of that locality) Size Range: ..46
Address2	string	Optional Employee's suite or apartment Size Range: ..46
City	string	Employee's city Size Range: ..50
State	string	Employee'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"
ZipCd	string	Employee's zip code Size Range: 5..10
ForeignAddress	object	If IsForeign is true, pass the foreign address of the employee
Address1	string	Employee's foreign address (street address or post office box of that locality) Size Range: ..50
Address2	string	Optional Employee's suite or apartment Size Range: ..50
City	string	Employee's city. Size Range: ..50
ProvinceOrStateNm	string	Employee's Province or State Name. Size Range: ..50
Country	string	Employee'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"
PostalCd	string	Employee's Postal Code. Size Range: ..16
DOB	string	Employee'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
HireDate	string	Employee's hire date. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY Example: 01/25/2025 or 01-25-2025
ReportingState	string	Reporting state. Refer Static values. Size Range: 2 Allowed values "SC"

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
BusinessId	Guid	Unique Identifier of the business
PayerRef	string	Unique identifier of the payer.
SuccessRecords	object[]	It will show the detailed information about the success status of New Hire Form Records.
SequenceId	string	A unique number given by an inbound application to identify failed records.
RecordId	Guid	Unique identifier of a record.
EmployeeId	Guid	Unique Identifier of the business
EmpRef	string	Unique identifier of the payer.
Status	string	Returns the status of the records.
StatusTs	string	Returns date and time of return created.
Info	string	Returns information about the Federal Filing service.
Errors	object[]	Shows error information of state returns of New Hire form
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
ErrorRecords	object[]	It will show the detailed information about the error status of NewHire Form Records.
SequenceId	string	An 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.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
    "ReturnHeader": {
        "Business": {
            "BusinessId": null,
            "BusinessNm": "SnowDaze LLC",
            "TradeNm": "Mayfill Tech",
            "IsEIN": true,
            "EINorSSN": "001687743",
            "Email": "john@sample.com",
            "IsForeign": false,
            "USAddress": {
                "Address1": "12 Main st",
                "Address2": "CC avenue",
                "City": "Rock Hill",
                "State": "SC",
                "ZipCd": "29730"
            },
            "ForeignAddress": {
                "Address1": null,
                "Address2": null,
                "City": null,
                "ProvinceOrStateNm": null,
                "Country": null,
                "PostalCd": null
            }
        }
    },
    "ReturnData": {
        "EmployeeDetails": [
            {
                "SequenceId": "1",
                "EmployeeId": null,
                "EmpRef": "2344",
                "SSN": "001456924",
                "FirstNm": "Henry",
                "MiddleNm": null,
                "LastNm": "Smith",
                "Suffix": null,
                "IsForeign": false,
                "USAddress": {
                    "Address1": "12 Main st",
                    "Address2": "CC avenue",
                    "City": "Rock Hill",
                    "State": "SC",
                    "ZipCd": "29730"
                },
                "ForeignAddress": null,
                "DOB": "10/12/1992",
                "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": "01993c3f-bd17-73ad-b4ca-8891c23f3118",
  "SuccessRecords": [
      {
          "SequenceId": "001",
          "BusinessId": "da40ab7f-e8dc-4091-834b-b564a437c895",
          "PayerRef": null,
          "RecordId": "01993c3f-bdd6-71f0-ac13-27cd4b663571",
          "FormType": "SC1605",
          "Status": "CREATED",
          "StatusTs": "2025-09-12 00:47:14 -04:00",
          "Info": null,
          "Errors": null
      },
      {
          "SequenceId": "002",
          "BusinessId": "df7b1d1b-62c3-4cb0-a564-3958c0bea9cf",
          "PayerRef": null,
          "RecordId": "01993c3f-c322-71d5-ab35-0f70f59d72b2",
          "FormType": "SC1606",
          "Status": "CREATED",
          "StatusTs": "2025-09-12 00:47:15 -04:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": null,
  "Errors": null
}

Multi-status Response - You'll get the below response when multiple statuses are included.

{
  "StatusCode": "300",
  "StatusName": "MultiStatus",
  "StatusMessage": "Multiple statuses are available for the request",
  "SubmissionId": "01996041-8534-770c-b794-4d0f9449ec18",
   "BusinessId": "07e6d7d9-5463-43d2-a272-14dc563cb5e0",
  "PayerRef": null,
  "SuccessRecords": [
      {
          "SequenceId": "1",
          "RecordId": "01996041-874f-771e-9eac-37cc2e2c63ab",
          "EmployeeId": "b3a91620-d26c-421e-95c6-1176522f105a",
          "EmpRef": "2344",
          "ReportingState": "SC",
          "Status": "CREATED",
          "StatusTs": "2025-09-19 00:35:31 -04:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": [
      {
          "SequenceId": "2",
          "RecordId": null,
          "Errors": [
              {
                  "Id": "S00-000311",
                  "Name": "SSN",
                  "Message": "SSN does not match with the given EmpRef"
              }
          ]
      }
  ],
  "Errors": [
      {
          "Id": "S00-000184",
          "Name": "Error Records",
          "Message": "Some of the records are errored. Please read the Error Records for more details."
      }
  ]
 
}

Bad Request Response - You'll get the below response when your API requests contain any validation errors.

 {
  "StatusCode": "400",
  "StatusName": "BadRequest",
  "StatusMessage": "Validation error has occurred",
  "SubmissionId": null,
  "PayerRef": null,
  "SuccessRecords": null,
  "ErrorRecords": [
      {
          "SequenceId": "1",
          "RecordId": null,
          "Errors": [
              {
                  "Id": "S00-000275",
                  "Name": "EmployeeDetails[0].HireDate",
                  "Message": "Invalid employee hired date. It should not be a future date"
              }
          ]
      }
  ],
  "Errors": null
}

Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.

{
  "StatusCode": 401,
  "StatusName": "Unauthorized",
  "StatusMessage": "Invalid authorization credentials",
  "Errors": [
      {
          "Id": "AUTH-100018",
          "Name": "Authorization",
          "Message": "JWT EXPIRED"
      }
  ]
}

W-9/W-8 Automation

1099 Automation

TIN Matching

W-2 Automation

941/940 Automation

1098-T Automation

ACA Automation

Extension Automation

Gig Software

Payroll Software

Affiliate Software

HOA Software

Reselling Platform

HCM Providers

Property Management

Supported Forms

Create

Create

Request Body

Response Body

Request JSON​

Response JSON​

Request JSON

Response JSON