Update

Update

Use this endpoint to update the information on existing NC-3 forms that are already created for a specific payer.

Note:

You cannot update a return once it has been transmitted.

PUTStateFilings/NC3ANNUALRECON/Update

Run in Postman

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
StateWHRecords	Object []	Object to create  NC-3
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-3.
Qtr	String	The Quarter for which Form  NC-3 needs to be filed. Allowed values "Q1", "Q2", "Q3", "Q4" Since Form NC-3 is an annual reconciliation form, it must be filed only for the fourth quarter of the tax year.
TaxYr	String	The tax year for which Form  NC-3 needs to be filed. Allowed values   2025
BusinessId	String	Optional Use the unique BusinessId (Generated by TaxBandits) you receivedin the response of the Business CREATE Endpoint. If you do not have aBusinesId, ignore the field. By giving the BusinessId, you do not have toprovide 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 isfalse, 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 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: 2Allowed 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: 2Allowed 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-3 data.
FormNC3	Object	North Carolina annual withholding reconciliation tax returnNote: Since Form NC-3 is an annual reconciliation form, it must be filed only for the fourth quarter of the tax year.
WHIdNum	String	North Carolina withholding account number. Size Range: 9
BusinessClosedDt	String	If the business was closed or stopped paying wages during the tax year, enter the date the business was closed in the format: MM/DD/YYYY or MM-DD-YYYY (Example: 01/25/2025).
TaxWHDetails	Object	Object that contains information about total tax withheld reported to the North Carolina Department for the tax year
L1Jan	Number	Total tax withheld reported to the North Carolina Department for the month of January. Size Range: 0-99999999.99
L2Feb	Number	Total tax withheld reported to the North Carolina Department for the month of February. Size Range: 0-99999999.99
L3Mar	Number	Total tax withheld reported to the North Carolina Department for the month of March. Size Range: 0-99999999.99
L4Apr	Number	Total tax withheld reported to the North Carolina Department for the month of April. Size Range: 0-99999999.99
L5May	Number	Total tax withheld reported to the North Carolina Department for the month of May. Size Range: 0-99999999.99
L6Jun	Number	Total tax withheld reported to the North Carolina Department for the month of June. Size Range: 0-99999999.99
L7Jul	Number	Total tax withheld reported to the North Carolina Department for the month of July. Size Range: 0-99999999.99
L7Aug	Number	Total tax withheld reported to the North Carolina Department for the month of August. Size Range: 0-99999999.99
L8Sep	Number	Total tax withheld reported to the North Carolina Department for the month of September. Size Range: 0-99999999.99
L10Oct	Number	Total tax withheld reported to the North Carolina Department for the month of October. Size Range: 0-99999999.99
L11Nov	Number	Total tax withheld reported to the North Carolina Department for the month of November. Size Range: 0-99999999.99
L12Dec	Number	Total tax withheld reported to the North Carolina Department for the month of December. Size Range: 0-99999999.99
L13TotTaxWH	Number	Total tax withheld reported to the North Carolina Department for all the months of the tax year. Size Range: 0-99999999.99
L14TaxWHRepW2	Number	Tax Withheld as Reported on W-2 Statements Size Range: 0-99999999.99
L15TaxWHRep1099	Number	Tax Withheld as Reported on 1099 Statements Size Range: 0-99999999.99
L16TotTaxWH	Number	Total Tax Withheld as Reported to the Department of North Carolina Size Range: 0-99999999.99
L17TotTaxWHRepW21099	Number	Total Tax Withheld as Reported on W-2 and 1099 Statements Size Range: 0-99999999.99
L18OverPayment	Number	Overpayment amount for the tax year. It is required only if Total Tax Withheld as Reported to the Department of North Carolina is greater than Total Tax Withheld as Reported on W-2 and 1099 Statements. *Size Range: 0-99999999.99
L19AddnlTaxDue	Number	Additional Tax Due for the tax year. It is required only if Total Tax Withheld as Reported on W-2 and 1099 Statements is greater than Total Tax Withheld as Reported to the Department of North Carolina *Size Range: 0-99999999.99
L20InterestAmt	Number	Interest amount for the tax year. Size Range: 0-99999999.99
L21Penalties	object	object that contains Informational Return Penalties details.
L21aLateFiling	Number	Penalty imposed, if any, for failure to file by the due date Size Range: 0-99999999.99
L21bFilingFormat	Number	Penalty imposed, if any, for failure to File in Format Size Range: 0-99999999.99
L21cTotPenalties	Number	Total penalties imposed for the tax year Size Range: 0-99999999.99
L22RefundAmt	Number	Amount of Refund Requested for the tax year. Size Range: 0-99999999.99
L23TotAmtDue	Number	Total Amount Due for the tax year Size Range: 0-99999999.99
StatePayment	Object	Object that contains information about payment details for the department of North Carolina
AccountType	String	Type of the bank account. Allowed values "PERSONAL_CHECKING", "PERSONAL_SAVINGS", "BUSINESS_SAVINGS", "BUSINESS_CHECKING"
BankRoutingNum	String	Bank routing number Size Range: 9
BankAccountNum	String	Bank Account Number Size Range: ..17
PaymentAmt	Number	Amount to be paid to the department of North Carolina 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-3 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 an  NC-3 return is created
FormType	string	Denotes the type of withholding form (Form  NC-3).
Status	string	Returns the record status of the 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-3
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-3 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

Update return for the first three quarters of the tax year

{
  "SubmissionId": "019c74aa-c3c0-75d9-b2e9-99c598afd56a",
  "StateWHRecords": [
      {
          "Sequence": "001",
          "ReturnHeader": {
              "Qtr": "Q4",
              "TaxYr": "2025",
              "Business": {
                  "BusinessId": "7da5863e-6ddf-4e31-ae09-f510260d30db"
              }
          },
          "ReturnData": {
              "RecordId": "019c74aa-c4a3-7114-acf4-c8fa2e2b1fc8",
              "FormNC5Q": null,
              "FormNC3": {
                  "WHIdNum": "173566979",
                  "BusinessClosedDt": "04/10/2025",
                  "TaxWHDetails": {
                      "L1Jan": 100,
                      "L2Feb": 100,
                      "L3Mar": 100,
                      "L4Apr": 100,
                      "L5May": 100,
                      "L6Jun": 100,
                      "L7Jul": 100,
                      "L8Aug": 100,
                      "L9Sep": 100,
                      "L10Oct": 100,
                      "L11Nov": 100,
                      "L12Dec": 100
                  },
                  "L13TotTaxWH": 1200,
                  "L14TaxWHRepW2": 1000,
                  "L15TaxWHRep1099": 200,
                  "L16TotTaxWH": 1200,
                  "L17TotTaxWHRepW21099": 1200,
                  "L18OverPayment": 0,
                  "L19AddnlTaxDue": 0,
                  "L20InterestAmt": 0,
                  "L21Penalties": {
                      "L21aLateFiling": 20,
                      "L21bFilingFormat": 0,
                      "L21cTotPenalties": 20
                  },
                  "L22RefundAmt": 0,
                  "L23TotAmtDue": 20
              },
              "StatePayment": {
                  "AccountType": "PERSONAL_CHECKING",
                  "BankRoutingNum": "217555555",
                  "BankAccountNum": "00133",
                  "PaymentAmt": 100
              }
          }
      }
  ]
}

Response JSON

200

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

{
  "StatusCode": "200",
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "0199e6d1-cea0-706d-8926-d7dad88478d3",
  "SuccessRecords": [
      {
          "SequenceId": "001",
          "BusinessId": "f88857c3-da9f-4655-976e-914124e53089",
          "PayerRef": null,
          "RecordId": "f88857c3-da9f-4655-976e-914124e53089",
          "FormType": "NC3",
          "Status": "UPDATED",
          "StatusTs": "2026-02-18 23:52:39 -05:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": null,
  "Errors": null
}

300

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": "019c7489-0246-726b-aec1-5fdc8dfe4d96",
  "SuccessRecords": [
      {
          "SequenceId": "001",
          "BusinessId": "06c839b9-eab3-4136-8851-9bd8dee230c2",
          "PayerRef": null,
          "RecordId": "019c7489-04e1-7006-89d1-f44f761c19d9",
          "FormType": "NC3",
          "Status": "UPDATED",
          "StatusTs": "2026-02-19 01:14:22 -05:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": [
      {
          "SequenceId": "001",
          "RecordId": null,
          "Errors": [
              {
                  "Id": "S00-000017",
                  "Name": "ReturnData[1].SequenceId",
                  "Message": "Duplicate sequence id exist. The sequence Id [001] is repeated more than once."
              }
          ]
      }
  ],
  "Errors": [
      {
          "Id": "S00-000184",
          "Name": "Error Records",
          "Message": "Some of the records are errored. Please read the Error Records for more details."
      }
  ]
}

400

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-000628",
                  "Name": "StateWHRecords[0].ReturnData.FormNC3.L13TotTaxWH",
                  "Message": "Invalid total tax withheld. This value should be equal to the sum of tax withheld in each month"
              }
                        ]
      }
  ],
  "Errors": null
}

401

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"
      }
  ]
}