Get
Get
Use this endpoint to retrieve the information of a previously created NC UI101 form for the corresponding employer (payer). Your request JSON must include the corresponding SubmissionId and the RecordId (optional) for the forms.
GET StateFilings/NCUI/Get Request Params
| Field | Type | Description |
|---|---|---|
| SubmissionId | Guid | Unique identifier of a submission. |
| RecordId | Guid | An unique identifier generated by TaxBandits when a G-7M/G-7Q return is created. Mention the return's Record ID that you want to get. |
Request Body
| Field | Type | Description |
|---|---|---|
| SubmissionId | Guid | Unique identifier created by TaxBandits for each submission. Not required when you are creating a return. |
| StateUIRecords | Object [] | Object to identify the records. |
| SequenceId | String | A unique identifier for this record. Size Range: ..10 |
| ReturnHeader | Object | Contains information about the Business details. |
| TaxYr | string | The tax year for which the Form UC101 is to be filed. Allowed values"2025" |
| Qtr | string | The quarter for which the Form UC101 is to be filed. Allowed values"Q1", "Q2", "Q3", "Q4" |
| Business | Object | Object to identify the Business Details. |
| BusinessId | Guid | Optional Use the unique Business ID provided in the response from the Business CREATE endpoint. |
| 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 | Optional Email address of the business. Size Range: ..100 | |
| ContactNm | string | Optional Name of the person who can be contacted by the IRS. Size Range: ..27 |
| Phone | string | Optional Phone 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 | Optional Type of business. Mandatory for 94X series and optional for W-2/1099. Size Range: 4 Allowed values"ESTE", "PART", "CORP", "EORG", "SPRO" |
| KindOfEmployer | string | Optional Identifies the kind of employer. Mandatory for W-2 and optional for 1099-NEC and 94X series.Allowed values"FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C","NONEAPPLY" |
| KindOfPayer | string | Optional Identifies the kind of payer. This field is mandatory for W-2 and optional in 1099-NEC and 94X series.Allowed values"REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1" |
| IsBusinessTerminated | Boolean | When true, indicates that the business is terminated. |
| IsForeign | Object | When true, indicates that the business has a foreign address. |
| USAddress | object | If IsForeign is false, pass the 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 the 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", |
| PostalCd | string | Employer/Payer's postal code. Size Range: ..16 |
| ReturnData | Object | Contains the return information. |
| NCUI101 | Object | Identifies the Form NCUI101 data. |
| IsChangeOfAddr | Boolean | When true, identifies the business has changed the address |
| IsDiffMailAdd | Boolean | When true, identifies the business has a different mailing address |
| MailAddress | Object | If IsDiffMailAdd is true, pass the mailing 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", |
| ZipCd | string | Employer/Payer's zip code. Size Range: 5..10 |
| UIIdNum | Object | Employer ID number. Sample format: XXXXXXXXXX |
| IsNoWageReported | Boolean | When true, indicates that no wage is reported in this quarter |
| TaxRate | Number | Tax rate for the quarter. Size Range: 1-100 |
| TaxDue | Number | Tax due for the quarter. *Size Range: 0-999999999.99 |
| Interest | Number | Optional Interest for the quarter. Size Range: 0-999999999.99 |
| PenaltyLateFiling | Number | Optional Late filing penalty for the quarter. Size Range: 0-999999999.99 |
| PenaltyLateFiling | Number | Optional Late filing penalty for the quarter. Size Range: 0-999999999.99 |
| BalanceDue | Number | Total Remittance due for the quarter. Size Range: 0-999999999.99 |
| L1NumOfEmployees | Object | Identifies the total number of employees for the quarter. |
| Month1Employees | string | Total number of employees in month 1 of the quarter. Size Range: 0-9999999 |
| Month2Employees | string | Total number of employees in month 2 of the quarter. Size Range: 0-9999999 |
| Month3Employees | string | Total number of employees in month 3 of the quarter. Size Range: 0-9999999 |
| EmployeeDetails | Object | Object to identify the Employee details. |
| EmpSequenceId | string | A unique number to identify this record. Size Range: ..10 |
| EmployeeId | Guid | Optional A unique ID generated by TaxBandits after the return is created and returned in the response. |
| EmpRef | string | A unique identifier of the employee. |
| SSN | string | Employee's Social Security Number (SSN). Size Range: 9-11 |
| FirstNm | string | Employee's first name. Size Range: 15 |
| MiddleNm | string | Optional Employee's middle name. Size Range: 15 |
| LastNm | string | Employee's last name. Size Range: 20 |
| Suffix | string | Optional Employee's suffix. Allowed values"Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII" |
| 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", |
| ZipCd | string | Employer/Payer's zip code. Size Range: 5..10 |
| GrossWages | Number | Gross wages of the employee. Size Range: ..99999999999.99 |
| OutOfStateTaxableWages | Number | Out of state taxable wages of the employee. Size Range: ..99999999999.99 |
| NumOfHrsWorked | Number | Optional Number of hours worked in the quarter by the employee Size Range:0-999 |
| IsEmployee | Boolean | When true, indicates that the employment type is employee |
| IsOfficer | Boolean | When true, indicates that the employment type is Officer |
| IsSeasonal | Boolean | When true, indicates the employee as seasonal. |
| LocationSummary | string | Indicates whether the location is the primary location.Allowed values"PRIMARY", "OTHER" |
| SOCCode | string | Standard Occupational Classification of the employee Sample Format: XX-XXXX Size Range: 6 digits |
| IsMonth1 | Boolean | When true, indicates the employee was employed during the month 1 of the quarter. |
| IsMonth2 | Boolean | When true, indicates the employee was employed during the month 2 of the quarter. |
| IsMonth3 | Boolean | When true, indicates the employee was employed during the month 3 of the quarter. |
| TotGrossWages | Number | Total gross wages reported for the quarter. Size Range: ..99999999999.99 |
| TotOOSTaxableWages | Number | Total out-of-state taxable wages reported for the quarter. Size Range: ..99999999999.99 |
| TotExcessWages | Number | Total Excess wages for the quarter. Size Range: ..99999999999.99 |
| TotTaxableWages | Number | Total Taxable wages for the quarter. Size Range: ..99999999999.99 |
Request Params
"Statefilings/NCUI/Get?RecordId=f5c0b155-7261-4f9d-b0bc-cad7a0f69d2e&SubmissionId=01993c45-e77e-7383-823a-d13273fd717c"
Response JSON
- 200
- 400
Success Response - This is a sample response for successful API requests.
{
"StateUIRecords": {
"SequenceId": "001",
"ReturnHeader": {
"Qtr": "Q1",
"TaxYr": "2025",
"Business": {
"BusinessId": null,
"BusinessNm": "Mayfill Tech LLC",
"TradeNm": "Mayfill Tech",
"IsEIN": true,
"EINorSSN": "001687743",
"Email": "mayfill.k@zolotech.com",
"ContactNm": "John",
"Phone": "7894561231",
"PhoneExtn": "12345",
"Fax": "7123547895",
"BusinessType": "ESTE",
"KindOfEmployer": null,
"KindOfPayer": null,
"IsBusinessTerminated": false,
"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": {
"FormNCUI101": {
"IsChangeOfAddr": false,
"UIIdNum": "1234567890",
"IsDiffMailAdd": true,
"MailAddress": {
"Address1": "12 Main st",
"Address2": "CC avenue",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"IsNoWageReported": false,
"TaxRate": 0.054,
"TaxDue": 1000,
"Interest": 0,
"PenaltyLateFiling": 0,
"PenaltyLatePayment": 0,
"BalanceDue": 280,
"NumOfEmployees": {
"Month1Employees": 10,
"Month2Employees": 20,
"Month3Employees": 30
},
"EmployeeDetails": [
{
"EmployeeSeqId": "11",
"EmployeeId": null,
"EmpRef": "Payee001",
"SSN": "761456924",
"FirstNm": "John",
"MiddleNm": "Joe",
"LastNm": "Smith",
"Suffix": "null",
"USAddress": {
"Address1": "12 Main st",
"Address2": "CC avenue",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"GrossWages": 1000,
"TaxableWages": 1000,
"ExcessWages": 0,
"OutOfStateTaxableWages": 200,
"OutOfStateCode": 123,
"NumOfHrsWrkd": 40,
"IsEmployee": true,
"IsOfficer": false,
"IsSeasonal": true,
"LocationSummary": "Primary",
"SOCCode": "123132",
"IsMonth1": true,
"IsMonth2": true,
"IsMonth3": true
},
{
"EmployeeSeqId": "11",
"RecipientId": null,
"PayeeRef": "Payee001",
"SSN": "761456924",
"FirstNm": "John",
"MiddleNm": "Joe",
"LastNm": "Smith",
"Suffix": "null",
"GrossWages": 1000,
"TaxableWages": 1000,
"ExcessWages": 0,
"OutOfStTaxableWages": 200,
"OutOfStCode": 123,
"NumOfHrsWrkd": 40,
"IsEmployee": true,
"IsOfficer": false,
"IsSeasonal": "Yes",
"LocationSummary": "Primary",
"SOCCode": "123132",
"IsMonth1": true,
"IsMonth2": true,
"IsMonth3": true
}
],
"TotGrossWages": 5000,
"TotOutOfStateTaxableWages": 2500,
"TotExcessWages": 600,
"TotTaxableWages": 1400
}
}
}
}
Success Response - This is a sample response for successful API requests.
{
"StatusCode": "400",
"StatusName": "BadRequest",
"StatusMessage": "Validation error has occurred",
"SubmissionId": null,
"StateWHRecords": null,
"Errors": [
{
"Id": "S00-000098",
"Name": "SubmissionId",
"Message": "SubmissionId is invalid."
}
]
}