Version: 1.7.3

Update

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

Note:

You cannot update a return once it has been transmitted.

PUTStateFilings/NYWH/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 Form NYS-1
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 NYS-1
Qtr	String	The quarter for which Form NYS-1 needs to be filed. Allowed values "Q1", "Q2", "Q3", "Q4"
TaxYr	String	The tax year for which Form NYS-1 needs to be filed. Allowed values 2025,2026
Business	Object	The details of the business you’re filing for.
BusinessNm	String	Name of the business. Size Range: ..75
PayerRef	string	Optional A unique identifier for each payer completing their information. This identifier can be used in future references to the payer in the API. Size Range: ..50
TradeNm	String	Optional Name under which the business operates. Size Range: ..75
IsEIN	Boolean	When true, it identifies the business with an EIN.
EINorSSN	String	When IsEIN is true, use Employer Identification Number (EIN). Size Range: 9-11
Email	String	Email address of the business. Size Range: ..100
IsForeign	Boolean	When true, it 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", "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). 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", "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"
PostalCd	String	Employer/Payer’s postal code. Size Range: ..16
ReturnData	Object	Identifies the Form WH-10001
FormNYS1	Object	New York State Return of Tax Withheld form data.
WHIdNum	String	New York withholding identification number.Note: Must begin with the employer's 9-digit EIN.
SPICode	String	Optional Special payroll indicator code. Size Range: 2
LastPayrollDt	String	Last date of payroll covered by this return.Sample Format: MM/DD/YYYY
IsAmendedReturn	Boolean	When true, it indicates this is an amended return.
PrevPayrollDt	String	Optional Payroll date from the original return being amendedSample Format: MM/DD/YYYY.
L1TotNYWHAmt	Number	New York State tax withheld. Do not include the NYC or Yonkers tax.Size Range: 0-9999999999.99
L2TotNYCWHAmt	Number	Optional New York City tax withheld. Leave blank if no NYC tax withheld.Size Range: 0-9999999999.99
L3YonkersWHAmt	Number	Optional Yonkers tax withheld. Size Range: 0-9999999999.99
L4TotWHAmt	Number	Total withheld Size Range: 0-9999999999.99
L5CreditAmt	Number	Optional Credit claimed from prior overpayment. Size Range: 0-9999999999.99
L6PrevPaidAmt	Number	Optional Amount previously paid (amended returns only). Size Range: 0-9999999999.99
L7TotTaxDue	Number	Total amount due. Size Range: 0-9999999999.99
NYTPRIN	String	New York Tax Preparer Registration Identification Number.
NYTPRINExclCode	String	NYTPRIN exclusion code. Allowed values : "01"–"10"

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 NYS-1 Records
SequenceId	string	A unique number given by an inbound application to identify a particular record.
BusinessId	Guid	Unique identifier of a Business
PayerRef	string	Unique identifier of the payer
RecordId	Guid	A unique identifier generated by TaxBandits when an NYS-1 return is created
FormType	string	Denotes the type of withholding form NYS-1.
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 NYS-1
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 NYS-1 Records.
SequenceId	string	A unique number given by an inbound application to identify a particular record. 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

{
    "SubmissionId": "019c706b-d45f-70f8-a2ce-8ccac111ea6f",
    "StateWHRecords": [
        {
            "SequenceId": "001",
            "RecordId": "019c706b-d5bd-718a-944a-4e1718a5b380",
            "ReturnHeader": {
                "Qtr": "Q1",
                "TaxYr": "2026",
                "Business": {
                    "BusinessId": "",
                    "BusinessNm": "QuickBooksLLC",
                    "TradeNm": null,
                    "IsEIN": true,
                    "EINorSSN": "72-7272727",
                    "Email": "saidineesha.s+001@spantechnologyservices.com",
                    "ContactNm": "EthanBrooks",
                    "Phone": "(444)123-3112",
                    "PhoneExtn": null,
                    "Fax": "(888)288-2828",
                    "BusinessType": "SCORP",
                    "KindOfEmployer": null,
                    "KindOfPayer": null,
                    "IsBusinessTerminated": false,
                    "IsForeign": false,
                    "USAddress": {
                        "Address1": "7900Sudley",
                        "Address2": "Rd",
                        "City": "Manassas",
                        "State": "VA",
                        "ZipCd": "20109"
                    },
                    "ForeignAddress": {
                        "Address1": null,
                        "Address2": null,
                        "City": null,
                        "ProvinceOrStateNm": null,
                        "Country": null,
                        "PostalCd": null
                    },
                    "SigningAuthority": {
                        "Name": "EthanBrooks",
                        "Phone": "(444)123-3112",
                        "BusinessMemberType": "VICEPRESIDENT"
                    }
                }
            },
            "ReturnData": {
                "FormNYS1": {
                    "WHIdNum": "72-7272727-12",
                    "SPICode": "23",
                    "LastPayrollDt": "7/21/2026",
                    "L1TotNYWHAmt": "1000.00",
                    "L2TotNYCWHAmt": "2000.00",
                    "L3YonkersWHAmt": "0.00",
                    "L4TotWHAmt": "3000.00",
                    "L5CreditAmt": "100.00",
                    "L6TaxPaid": "200.00",
                    "L7TotTaxDue": "2700.00",
                    "NYTPRIN": "dgd1223",
                    "NYTPRINExclCode": "10"
                }
            }
        }
    ]
}

Response JSON

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

{
  "StatusCode": "200",
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "019c706b-d45f-70f8-a2ce-8ccac111ea6f",
  "SuccessRecords": [
      {
          "SequenceId": "001",
          "BusinessId": "620c73f3-aed2-4630-9e42-bcebddbc7fda",
          "PayerRef": "Snow1546ty",
          "RecordId": "019c706b-d5bd-718a-944a-4e1718a5b380",
          "FormType": "NYS1",
          "Status": "UPDATED",
          "StatusTs": "2026-02-18 06:04:01 -05:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": null,
  "Errors": null
}

Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.

{
  "StatusCode": 401,
  "StatusMessage": "Unauthorized",
  "StatusName": "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

1042-S Automation

Supported Forms

Gig Software

Payroll Software

Affiliate Software

HOA Software

Reselling Platform

HCM Providers

Property Management

Healthcare Market Research Platforms

Update

Update

Request Body

Response Body

Request JSON​

Response JSON​

Request JSON

Response JSON