Version: 1.7.3

Create

Use this endpoint to generate new withholding filings for the state of North Carolina. For North Carolina, there is a specific requirement, unlike some other states, where quarterly and annual reconciliation forms must both be filed (NC-5Q/NC-3).

Form NC-5Q: Used to report quarterly withholding tax totals for wages paid and North Carolina income tax withheld during the quarter.

Form NC-3: Used to report the annual reconciliation of North Carolina income tax withheld and to submit W-2 and 1099 withholding statements for the tax year.

POST StateFilings/NCWH/Create

Run in Postman

Request Body

Field	Type	Description
StateWHRecords	Object []	Object to create NC-5Qs
SequenceId	String	A unique number given by an inbound application to identify failed records. Size Range: ..10
ReturnHeader	Object	Identifies the supporting details of Form NC-5Q.
Qtr	String	The Quarter for which Form NC-5Q needs to be filed. Allowed values "Q1", "Q2", "Q3", "Q4"
TaxYr	String	The tax year for which Form NC-5Q needs to be filed. Allowed values 2025
BusinessId	String	Optional 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.
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
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" For the description of the Allowed Values , click here
SigningAuthority	Object	Details of the person who is authorized to sign the return.
Name	String	Optional Name of the signing authority. Size Range: ..75
Phone	String	Optional Phone number of the signing authority. Size Range: 10
BusinessMemberType	String	Optional Business title of the authorized signatory. Size Range: 5..29 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"
IsForeign	Boolean	When true, identifies the business as having a foreign address.
USAddress	Object	If IsForeign is false, pass the US address of the business.
Address1	String	Employer/Payer’s US address (street address or post office box). 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. Size Range: 2 Allowed values "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", etc.
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). 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", etc.
PostalCd	String	Employer/Payer’s postal code. Size Range: ..16
ReturnData	Object[]	Identifies the Form NC-5Q data.
FormNC5Q	Object	North Carolina withholding quarterly tax return.
WHIdNum	String	North Carolina withholding account number. Size Range: 9
L1TotWHTaxLiability	Number	Total tax required to be withheld Size Range: 0-99999999.99
L2TotTaxDeposit	Number	Total payments to North Carolina for quarter Size Range: ..11 Size Range: 0-99999999.99
L3BalanceDue	Number	Balance 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
L4OverPayment	Number	Over 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
DepositSchedule	String	Deposit schedule of the tax deposits Allowed values "SemiWeekly"
SemiWeeklyDepositor	Object	Object to identify the semi weekly deposit schedule details
Month1TaxLiability	Object []	Object to identify the tax liability details for the first month of the quarter
Day	String	Tax 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"
Amt	Number	Tax liability amount of the pay day. Size Range: 0-99999999.99
Month1TotTaxLiability	Number	Total tax required to be withheld for first month of quarter Size Range: 0-99999999.99
Month2TaxLiability	Object []	Object to identify the tax liability details for the second month of the quarter
Day	String	Tax 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"
Amt	Number	Tax liability amount of the pay day. Size Range: 0-99999999.99
Month2TotTaxLiability	Number	Total tax required to be withheld for second month of quarter Size Range: 0-99999999.99
Month3TaxLiability	Object []	Object to identify the tax liability details for the third month of the quarter
Day	String	Tax Liability pay day of third 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"
Amt	Number	Tax liability amount of the pay day Size Range: 0-99999999.99
Month3TotTaxLiability	Number	Total tax required to be withheld for third month of quarter Size Range: 0-99999999.99
TotQtrTaxLiabilityAmt	Number	Total tax required to be withheld for all the months of the quarter Size Range: 0-99999999.99

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
SuccessRecords	object[]	It will show the detailed information about the success status of Form NC-5Q Records
SequenceId	string	A unique number given by an inbound application to identify particular records.
BusinessId	Guid	Unique identifier of a Business
PayerRef	string	Unique identifier of the payer
RecordId	Guid	An unique identifier generated by TaxBandits when a NC-5Q return is created
FormType	string	Denotes the type of withholding form (Form NC-5Q).
Status	string	Returns the record status of return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the return
Errors	object[]	Shows error information of state returns of Form NC-5Q
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 Form NC-5Q Records.
SequenceId	string	A unique number given by an inbound application to identify particular records. The Sequence ID will be returned in the Response for your reference.
RecordId	Guid	Unique identifier of a record
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

Sample 1

Create return for the NC-5Q 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": "34-4985746",
                  "Email": "john@gmail.com",
                    "BusinessType": "ESTE",
                  "SigningAuthority": {
                      "Name": "James Smith",
                      "Phone": "9934567890",
                      "BusinessMemberType": "ADMINISTRATOR"
                  },
                  "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": {
                      "Month1TaxLiability": [
                          {
                              "Day": "01",
                              "Amt": 1000
                          }
                      ],
                      "Month1TotTaxLiability": 1000,
                      "Month2TaxLiability": [
                          {
                              "Day": "01",
                              "Amt": 1000
                          }
                      ],
                      "Month2TotTaxLiability": 1000,
                      "Month3TaxLiability": [
                          {
                              "Day": "01",
                              "Amt": 1000
                          }
                      ],
                      "Month3TotTaxLiability": 1000
                  },
                  "TotQtrTaxLiabilityAmt": 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
}

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": "0199e6ce-1aba-7718-96c0-505f9423cd78",
  "SuccessRecords": [
      {
          "SequenceId": "002",
          "BusinessId": "4d342818-7d8e-4c71-a995-d6e36158d317",
          "PayerRef": null,
          "RecordId": "0199e6ce-1b86-70ef-9ff9-e03aa37ae43c",
          "FormType": "NC5Q",
          "Status": "UPDATED",
          "StatusTs": "2025-10-15 03:38:11 -04:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": [
      {
          "SequenceId": "001",
          "RecordId": null,
          "Errors": [
              {
                  "Id": "S00-000448",
                  "Name": "StateWHRecords[0].ReturnData.FormNC5Q.L4OverPayment",
                  "Message": "Over payment amount is required if total tax required to be withheld amount is less than total tax deposits"
              }            ]
      }
  ],
  "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,
  "SuccessRecords": null,
  "ErrorRecords": [
      {
          "SequenceId": "001",
          "RecordId": null,
          "Errors": [
              {
                  "Id": "S00-000448",
                  "Name": "StateWHRecords[0].ReturnData.FormNC5Q.L4OverPayment",
                  "Message": "Over payment amount is required if total tax required to be withheld amount is less than total tax deposits"
              }
          ]
      }
  ],
  "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