Skip to main content
Version: 1.7.3

Create

Create

Use this endpoint to generate a new withholding form for the state of North Carolina.

POST StateFilings/NCWH/Create
Run in Postman

Request Body

FieldTypeDescription
StateWHRecordsObject []Object to create NC-5Qs
SequenceIdStringA unique number given by an inbound application to identify failed records.
Size Range: ..10
ReturnHeaderObjectIdentifies the supporting details of Form NC-5Q.
QtrStringThe Quarter for which Form NC-5Q needs to be filed.
Allowed values

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

TaxYrStringThe tax year for which Form NC-5Q needs to be filed.
Allowed values

2025

BusinessIdStringOptional Use the unique BusinessId (Generated by TaxBandits) you received in the response of the Business CREATE Endpoint. If you do not have a BusinesId, ignore the field. By giving the BusinessId, you do not have to provide all the business information again.
BusinessObjectThe details of the business you’re filing for.
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 as having a foreign address.
USAddressObjectIf IsForeign is false, pass the US address of the business.
Address1StringEmployer/Payer’s US address (street address or post office box).
Size Range: ..46
Address2StringOptional Employer/Payer’s suite or apartment.
Size Range: ..46
CityStringEmployer/Payer’s city.
Size Range: ..50
StateStringEmployer/Payer’s state.
Size Range: 2
Allowed values

"AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", etc.

ZipCdStringEmployer/Payer’s zip code.
Size Range: 5..10
ForeignAddressObjectIf IsForeign is true, pass the foreign address of the business.
Address1StringEmployer/Payer’s foreign address (street address or post office box).
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", etc.

PostalCdStringEmployer/Payer’s postal code.
Size Range: ..16
ReturnDataObject[]Identifies the Form NC-5Q data.
FormNC5QObjectNorth Carolina withholding quarterly tax return.
WHIdNumStringNorth Carolina withholding account number.
Size Range: 9
L1TotWHTaxLiabilityNumberTotal tax required to be withheld
Size Range: 0-99999999.99
L2TotTaxDepositNumberTotal payments to North Carolina for quarter
Size Range: ..11
Size Range: 0-99999999.99
L3BalanceDueNumberBalance due amount for the quarter.Note: Balance due amount is required only if L1TotWHTaxLiability is greater than L2TotTaxDeposit
Size Range: ..11
Size Range: 0-99999999.99
L4OverPaymentNumberOver payment amount for the quarter.Note: Over payment amount is required only if L2TotTaxDeposit is greater than L1TotWHTaxLiability
Size Range: ..11
Size Range: 0-99999999.99
DepositScheduleStringDeposit schedule of the tax deposits
Allowed values

"SemiWeekly"

SemiWeeklyDepositorObjectObject to identify the semi weekly deposit schedule details
Month1TaxLiabObject []Object to identify the tax liability details for the first month of the quarter
DayStringTax Liability pay day of first month of the quarter.
Allowed values

"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31"

AmtNumberTax liability amount of the pay day.
Size Range: 0-99999999.99
Month1TotTaxLiabNumberTotal tax required to be withheld for first month of quarter
Size Range: 0-99999999.99
Month2TaxLiabObject []Object to identify the tax liability details for the second month of the quarter
DayStringTax Liability pay day of second month of the quarter.
Allowed values

"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31"

AmtNumberTax liability amount of the pay day.
Size Range: 0-99999999.99
Month2TotTaxLiabNumberTotal tax required to be withheld for second month of quarter
Size Range: 0-99999999.99
Month3TaxLiabObject []Object to identify the tax liability details for the second month of the quarter
DayStringTax Liability pay day of second month of the quarter.
Allowed values

"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31"

AmtNumberTax liability amount of the pay day
Size Range: 0-99999999.99
Month3TotTaxLiabNumberTotal tax required to be withheld for second month of quarter
Size Range: 0-99999999.99
TotQtrTaxLiabAmtNumberTotal tax required to be withheld for all the months of the quarter
Size Range: 0-99999999.99

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission
SuccessRecordsobject[]It will show the detailed information about the success status of Form NC-5Q Records
SequenceIdstringA unique number given by an inbound application to identify particular records.
BusinessIdGuidUnique identifier of a Business
PayerRefstringUnique identifier of the payer
RecordIdGuidAn unique identifier generated by TaxBandits when a NC-5Q return is created
FormTypestringDenotes the type of withholding form (Form NC-5Q).
StatusstringReturns the record status of return.
StatusTsstringDate and time of the return created.
InfostringReturns the information about the return
Errorsobject[]Shows error information of state returns of Form NC-5Q
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 Form NC-5Q Records.
SequenceIdstringA unique number given by an inbound application to identify particular records. The Sequence ID will be returned in the Response for your reference.
RecordIdGuidUnique identifier of a record
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​

Create return for the first three quarters of the tax year

{
  "StateWHRecords": [
      {
          "Sequence": "001",
          "ReturnHeader": {
              "Qtr": "Q4",
              "TaxYr": "2025",
              "PayerRef": "Pe6258",
              "BusinessId": null,
              "Business": {
                  "BusinessNm": "SnowDaze LLC",
                  "TradeNm": null,
                  "IsEIN": true,
                  "EINorSSN": "73-6348743",
                  "Email": "john@sample.com",
                  "IsForeign": false,
                  "USAddress": {
                      "Address1": "12 main st",
                      "Address2": null,
                      "City": "Rock Hill",
                      "State": "SC",
                      "ZipCd": "29730"
                  },
                  "ForeignAddress": null
              }
          },
          "ReturnData": {
              "FormNC5Q": {
                  "WHIdNum": "663838756",
                  "L1TotWHTaxLiability": 3000,
                  "L2TotTaxDeposit": 4000,
                  "L3BalanceDue": 0,
                  "L4OverPayment": 1000,
                  "DepositSchedule": "SemiWeekly",
                  "SemiWeeklyDepositor": {
                      "Month1TaxLiab": [
                          {
                              "Day": "01",
                              "Amt": 1000
                          }
                      ],
                      "Month1TotTaxLiab": 1000,
                      "Month2TaxLiab": [
                          {
                              "Day": "01",
                              "Amt": 1000
                          }
                      ],
                      "Month2TotTaxLiab": 1000,
                      "Month3TaxLiab": [
                          {
                              "Day": "01",
                              "Amt": 1000
                          }
                      ],
                      "Month3TotTaxLiab": 1000
                  },
                  "TotQtrTaxLiabAmt": 3000
              }
          }
      }
  ]
}

Response JSON​

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

{
  "StatusCode": "200",
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "0199e6bc-7079-70d3-8553-de6f9116feca",
  "SuccessRecords": [
      {
          "SequenceId": "001",
          "BusinessId": "e928f7dd-c0b4-4292-af71-0d4a65ac340c",
          "PayerRef": null,
          "RecordId": "0199e6bc-7172-7445-8e36-3d04b7d7d531",
          "FormType": "NC5Q",
          "Status": "CREATED",
          "StatusTs": "2025-10-15 03:18:53 -04:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": null,
  "Errors": null
}