Skip to main content
Version: 2.0.0

Update

Update

Use this endpoint to update the information on existing NC UI101 forms that are already created for a specific employer (payer).

You cannot update a return once it has been transmitted.

PUT StateFilings/NCUI/Update 

Request Body

FieldTypeDescription
SubmissionIdGuidUnique identifier created by TaxBandits for each submission. Not required when you are creating a return.
StateUIRecordsObject[]Object to identify the records.
SequenceIdStringA unique identifier for this record. Size Range: ..50
ReturnHeaderObjectContains business information.
TaxYearStringThe tax year for which the Form NCUI101 is to be filed.
Allowed values

2025,2026

QtrStringThe quarter for which the Form NCUI101 is to be filed.
Allowed values

"Q1", "Q2", "Q3", "Q4"

BusinessobjectObject to identify the Business Details.
BusinessIdGuidOptional Use the unique Business ID (Generated by TaxBandits) that you received in the response of the Business CREATE Endpoint. If you 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.
PayerRefstringOptional Your unique identifier for the payer. Can replace BusinessId in future requests. Size Range: 50
IsDefaultBusinessBooleanWhen set to TRUE, this business will be set as the default across requests that do not specify a business.
TINDetailsobjectTIN information for the business.
FormatstringSpecifies how the TIN is passed.
Allowed values

"PLAIN_TIN" — Pass TIN directly. "TOKENIZED_TIN" — Pass tokenized TIN.

TINTypestringSpecify the TIN type of the business.
Allowed values

"EIN", "SSN", "QI-EIN", "ITIN", "WP-EIN", "WT-EIN", "NQI-EIN", "IRSN"

TINstringThe TIN value according to the Format selected.
IndividualNmobjectOptional Required when TINType is SSN. Provide individual name fields instead of BusinessNm.
FirstNmstringThe first name of the individual. Size Range: 20
MiddleNmstringOptional Middle name of the individual. Size Range: 20
LastNmstringThe last name of the individual. Size Range: 20
SuffixstringOptional Suffix of the individual's name.
Allowed values

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

BusinessNmstringLegal name of the business. Required when TINType is EIN. Size Range: 75
NameCtrlstringName control of the business as registered with the IRS. Size Range: 3..4
DBADetailsobject[]Optional DBA (Doing Business As) information.
DBANmstringName of the DBA. Size Range: 75
DBARefstringUnique identifier for the DBA. Size Range: 1-50
DBAIdGuidTaxBandits-generated DBA identifier.
Addressobject[]Address information of the DBA.
Address1stringStreet address or PO Box. Size Range: 46
Address2stringOptional Suite or apartment number. Size Range: 46
CitystringDBA's city. Size Range: 50
ProvinceOrStatestringDBA's province or state name.
When the country code is US:
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"

When the country code is CA:
Allowed values

"AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT"

Note: The size range is set to 50 for all countries except the United States and Canada.
ZipcdstringDBA's ZIP code. Size Range: 5-16
CountrystringDBA's 2-character country code.
Allowed values

"US","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"

EmailstringOptional Email address of the Business. Size Range: ..100
AddressobjectPrimary address of the business.
Address1stringStreet address or PO Box of the business. Size Range: 46
Address2stringOptional Suite or apartment number of the business. Size Range: 46
CitystringCity of the business. Size Range: 50
ProvinceOrStatestringProvince or state name of the business.
When the country code is US:
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"

When the country code is CA:
Allowed values

"AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT"

Note: The size range is set to 50 for all countries except the United States and Canada.
ZipCdstringZIP code of the business. Size Range: 5-16
Countrystring2-character country code of the business.
Allowed values

"US","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"

ContactDetailsobject[]Details of the person the IRS can contact regarding the given business.
FirstNmstringFirst name of the contact person. Size Range: 20
MiddleNmstringOptional Middle name of the contact person. Size Range: 20
LastNmstringLast name of the contact person. Size Range: 20
SuffixstringOptional The suffix of the contact person.
Allowed values

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

PhonestringOptional Phone number of the contact person. Size Range: 10 digits
PhoneExtnstringOptional Phone extension number. Size Range: 5
EmailstringOptional Email address of the contact person. Size Range: ..100
FaxstringOptional Fax number of the contact person. Size Range: 10 digits
ReturnDataObjectContains the return information.
BusinessTypeStringLegal structure of the business.
Allowed values

"ESTE", "PART", "CORP", "EORG", "SPRO"

SigningAuthorityObjectDetails of the person authorized to sign the return. Mandatory for 94x forms.
FirstNmStringFirst name of the signatory. Size Range: 20
MiddleNmStringOptional Middle name of the signatory. Size Range: 20
LastNmStringLast name of the signatory. Size Range: 20
SuffixStringOptional The suffix of the signatory.
Allowed values

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

PhoneStringOptional Phone number of the signatory. Size Range: 10
PhoneExtnStringOptional Phone extension number of the signatory. Size Range: 5
BusinessMemberTypeStringOptional Title or role of the signatory.
Allowed values

"CORPORATESECRETARY", "SECRETARYTREASURER", "PARTNER", "GENERALPARTNER", "LIMITEDPARTNER", "LLCMEMBER", "MANAGINGMEMBER", "MANAGER", "TAXMATTERPARTNER", "PRESIDENT", "VICEPRESIDENT", "CORPORATETREASURER", "TREASURER", "ASSISTANTTREASURER", "CHIEFACCOUNTINGOFFICER", "CHIEFEXECUTIVEOFFICER", "CHIEFFINANCIALOFFICER", "TAXOFFICER", "CHIEFOPERATINGOFFICER", "CORPORATEOFFICER", "EXECUTIVEDIRECTOR", "DIRECTOR", "CHAIRMAN", "EXECUTIVEADMINISTRATOR", "RECEIVER", "PASTOR", "ASSISTANTTORELIGIOUSLEADER", "REVEREND", "PRIEST", "MINISTER", "RABBI", "LEADEROFRELIGIOUSORGANIZATION", "SECRETARY", "DIRECTOROFTAXATION", "DIRECTOROFPERSONNEL", "ADMINISTRATOR", "EXECUTOR", "TRUSTEE", "FIDUCIARY", "OWNER", "SOLEPROPRIETOR", "MEMBER", "SOLEMEMBER", "REPORTINGAGENT"

ReturnDataObjectContains the return information.
NCUI101ObjectIdentifies the Form NCUI101 data.
IsChangeOfAddrBooleanWhen true, identifies the business has changed the address.
IsDiffMailAddrBooleanWhen true, identifies the business has a different mailing address.
MailAddrObjectOptional If IsDiffMailAddr is true, pass the mailing 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. 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
UIIdNumstringEmployer ID number. Sample format: XXXXXXXXXX
IsNoWageReportedBooleanWhen true, indicates that no wage is reported in this quarter.
UITaxRateNumberTax rate for the quarter. Size Range: 1-100
UITaxDueNumberTax due for the quarter. Size Range: 0-999999999.99
InterestNumberOptional Interest for the quarter. Size Range: 0-999999999.99
LateFilingPenaltyNumberOptional Late filing penalty for the quarter. Size Range: 0-999999999.99
LatePaymentPenaltyNumberOptional Late payment penalty for the quarter. Size Range: 0-999999999.99
TotUIDueNumberTotal Remittance due for the quarter. Size Range: 0-999999999.99
NumOfEmpObjectIdentifies the total number of employees for the quarter.
TotMonth1EmpstringTotal number of employees in month 1 of the quarter. Size Range: 0-9999999
TotMonth2EmpstringTotal number of employees in month 2 of the quarter. Size Range: 0-9999999
TotMonth3EmpstringTotal number of employees in month 3 of the quarter. Size Range: 0-9999999
EmpDetailsObject[]Object to identify the Employee details.
EmployeeSequenceIdstringA unique number to identify this record. Size Range: ..10
EmpIdGuidOptional A unique ID generated by TaxBandits after the return is created and returned in the response.
EmployeeRefstringA unique identifier of the employee.
SSNstringEmployee's Social Security Number (SSN). Size Range: 9-11
FirstNmstringEmployee's first name. Size Range: 15
MiddleNmstringOptional Employee's middle name. Size Range: 15
LastNmstringEmployee's last name. Size Range: 20
SuffixstringOptional Employee's suffix.
Allowed values

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

GrossWagesNumberGross wages of the employee. Size Range: ..99999999999.99
TaxableWages
ExcessWages
OutOfStateTaxableWagesNumberOptional Out of state taxable wages of the employee. Size Range: ..99999999999.99
OutOfStateCdStringOptional Out of state code. 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"

NumOfHrsWorkedNumberOptional Number of hours worked in the quarter by the employee. Size Range: 0-999
IsEmployeeBooleanWhen true, indicates that the employment type is employee.
IsOfficerBooleanWhen true, indicates that the employment type is Officer.
IsSeasonalBooleanWhen true, indicates the employee as seasonal.
LocationSummarystringIndicates whether the location is the primary location.
Allowed values

"PRIMARY", "OTHER"

SOCCodestringStandard Occupational Classification of the employee. Sample Format: XX-XXXX, Size Range: 6 digits
IsMonth1BooleanOptional When true, indicates the employee was employed during the month 1 of the quarter.
IsMonth2BooleanOptional When true, indicates the employee was employed during the month 2 of the quarter.
IsMonth3BooleanOptional When true, indicates the employee was employed during the month 3 of the quarter.
TotGrossWagesNumberTotal gross wages reported for the quarter. Size Range: ..99999999999.99
TotOOSTaxableWagesNumberTotal out-of-state taxable wages reported for the quarter. Size Range: ..99999999999.99
TotExcessWagesNumberTotal Excess wages for the quarter. Size Range: ..99999999999.99
TotTaxableWagesNumberTotal Taxable wages for the quarter. Size Range: ..99999999999.99

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier for a submission.
SuccessRecordsobject[]Provides detailed information about the success status of Form NC UI101 records.
SequenceIdstringA 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.
BusinessIdGuidUnique identifier for the business (payer) generated by TaxBandits.
PayerRefstringUnique identifier for the business (payer) provided by you.
RecordIdGuidA unique identifier generated by TaxBandits when a Form NC UI101 return is created.
FormTypestringType of form.
EmployeeDataobject[]Object to identify the employee details.
EmployeeIdGuidReturns the unique identifier of the employee generated by TaxBandits.
EmployeeRefstringReturns the unique identifier of the employee provided by you.
RemoveEmployeeDataobject[]Object to identify employees removed from the return.
StatusstringReturns the record status.
StatusTsstringReturns the date and time when the return was created.
InfostringProvides additional information about the return.
Errorsobject[]Displays error information related to the state returns of Form NC UI101.
IdstringReturns the validation error ID.
NamestringName of the validation error.
ErrorRecordsobject[]Provides detailed information about the error status of Form NC UI101 records.
SequenceIdstringA 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.
RecordIdGuidUnique identifier for the record.
Errorsobject[]Displays detailed error information.
IdstringReturns the validation error ID.
NamestringName of the validation error.
MessagestringDescription of the validation error.

Request JSON​

{
"SubmissionId": "01a0e797-9629-704c-861a-4ff1e3138be2",
"StateUIRecords": [
{
"SequenceId": "002",
"RecordId": "01a0e797-9e9d-725e-87f2-1cbbfe147d3c",
"ReturnHeader": {
"Qtr": "Q3",
"TaxYear": "2026",
"Business": {
"IsDefaultBusiness": true,
"TINDetails": {
"Format": "PLAIN_TIN",
"TINType": "EIN",
"TIN": "459099203"
},
"IndividualNm": {
"FirstNm": "James",
"MiddleNm": "A",
"LastNm": "Anderson",
"Suffix": "Jr"
},
"BusinessNm": "Snowdaze LLC",
"NameCtrl": "FIRE",
"DBADetails": {
"DBANm": "Iceberg Icecreams",
"DBARef": "",
"DBAId": null,
"Address": {
"Address1": "123 Main St",
"Address2": "Suite 1001",
"City": "Rock Hill",
"ProvinceOrState": "SC",
"ZipCd": "29730",
"Country": "US"
}
},
"Address": {
"Address1": "123 Main St",
"Address2": "Suite 1001",
"City": "Rock Hill",
"ProvinceOrState": "SC",
"ZipCd": "29730",
"Country": "US"
},
"ContactDetails": {
"FirstNm": "James",
"MiddleNm": "A",
"LastNm": "Anderson",
"Suffix": "Jr",
"Phone": "8035551234",
"PhoneExtn": "101",
"Email": "contact@snowdaze.com",
"Fax": "8035555678"
},
"BusinessType": "ESTE",
"SigningAuthority": {
"FirstNm": "Ambrane",
"MiddleNm": "A",
"LastNm": "Cavil",
"Suffix": "Jr",
"Phone": "8035551000",
"PhoneExtn": "111",
"BusinessMemberType": "ADMINISTRATOR"
}
}
},
"ReturnData": {
"FormNCUI101": {
"IsChangeOfAddr": true,
"UIIdNum": "3801264739",
"IsDiffMailAddr": true,
"MailAddr": {
"Address1": "150 Fayetteville St",
"Address2": "Suite 200",
"City": "Raleigh",
"ProvinceOrState": "NC",
"ZipCd": "27604",
"Country": "US"
},
"IsNoWageRptd": false,
"UITaxRate": 1,
"UITaxDue": 45,
"Interest": 155,
"LateFilingPenalty": 60,
"LatePaymentPenalty": 40,
"TotUIDue": 300,
"NumOfEmp": {
"TotMonth1Emp": 1,
"TotMonth2Emp": 1,
"TotMonth3Emp": 1
},
"EmpDetails": [
{
"EmployeeSequenceId": "01",
"EmployeeId": "",
"EmployeeRef": "Empref50",
"SSN": "761-45-9778",
"FirstNm": "John",
"MiddleNm": "Joe",
"LastNm": "Smith",
"Suffix": "Jr",
"Address": {
"Address1": "400 Bellemeade St",
"Address2": "Apt 101",
"City": "Greensboro",
"ProvinceOrState": "NC",
"ZipCd": "27401",
"Country": "US"
},
"GrossWages": 6000,
"OutOfStateTaxableWages": null,
"OutOfStateCd": null,
"NumOfHrsWrkd": 28,
"IsEmployee": true,
"IsOfficer": false,
"IsSeasonal": true,
"LocationSummary": "Other",
"SOCCode": "123132"
}
],
"TotGrossWages": 6000,
"TotOutOfStateTaxableWages": 0,
"TotExcessWages": 1500,
"TotTaxableWages": 4500
}
}
}
]
}

Response JSON​

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

{
"SubmissionId": "01a0e797-9629-704c-861a-4ff1e3138be2",
"SuccessRecords": [
{
"SequenceId": "002",
"BusinessId": "b3ede465-204a-4205-9641-d6ff0a40c635",
"PayerRef": null,
"RecordId": "01a0e797-9e9d-725e-87f2-1cbbfe147d3c",
"FormType": "UI101",
"EmployeeData": [
{
"EmployeeId": "5D52556D-DEF9-46AE-B9E3-87AB57F96BAD",
"EmployeeRef": "Empref50"
}
],
"RemoveEmployeeData": null,
"Status": "CREATED",
"StatusTs": "2026-09-28 06:38:51 -04:00",
"Info": null,
"Errors": null
}
],
"ErrorRecords": null,
"Errors": null
}