Version: 2.0

Update

This endpoint modifies the details of an existing recipient in the TaxBandits API. Use this when a recipient’s name, address, TIN, contact information, or any other detail needs to be corrected or changed after creation.

Identify the recipient using either its RecipientId or PayeeRef. Multiple recipients can be updated in a single request by passing multiple objects in the Recipients array.

Changes apply to any in-progress returns associated with the recipient. Updates will not impact returns that have already been transmitted.

Key Points

TIN Format — The TIN Format (PLAIN_TIN, ENCRYPTED, TOKEN) can be changed during an update.
PayeeRef — DBA details can be updated here, or separately using the UpdateDBA endpoint.
Identifiers Unchanged — Updating a recipient does not change its RecipientId or PayeeRef.

For the description of ENUM values, click here.

PUT recipient/update

Run in Postman

Request Body

Field	Type	Description
Recipients	object []	An array of recipient objects. Pass multiple objects to update recipients in bulk.
SequenceId	String	Optional A 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. Max 50 characters
RecipientId	GUID	TaxBandits-generated unique identifier for the recipient. Required if `PayeeRef` is not provided.
PayeeRef	string	Optional Your unique identifier for the recipient. Required if `RecipientId` is not provided. Max 50 characters
TINDetails	Object	TIN information for the recipient
Format	String	Specifies how the TIN is passed. Allowed values "PLAIN_TIN" — Pass TIN directly.
TINType	string	Specify the TIN type of the recipient. Allowed values "EIN", "SSN", “QI-EIN”, “ITIN”, “WP-EIN”, “WT-EIN”, “NQI-EIN”, “IRSN”
TIN	string	The TIN value, formatted according to the `Format` field selected.
IndividualNm	Object	Required when `TINType` is SSN, ITIN, or ATIN. Provide individual name fields instead of `BusinessNm`.
FirstNm	String	The first name of the individual. Max 20 characters
MiddleNm	String	Optional The middle name of the individual. Max 20 characters
LastNm	String	The last name of the individual. Max 20 characters
Suffix	String	Optional The suffix of the individual's name. Allowed values "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
BusinessNm	String	Legal name of the recipient business. Required when `TINType` is EIN. Max 75 characters
DBADetails	Object	Optional DBA (Doing Business As) information. Optional at creation - additional DBAs can be added later via AddDBA.
DBANm	String	Name of the DBA. Max 75 characters
DBARef	String	Your unique identifier for this DBA. 1-50 characters
DBAId	GUID	TaxBandits-generated DBA identifier. Returned in the response.
Address	Object	Address information of DBA.
Address1	String	Street address or PO Box. Max 46 characters
Address2	String	Optional Suite or apartment number. Max 46 characters
City	String	DBA's city. Max 50 characters
ProvinceOrState	String	DBA's province or state name. Allowed values When the country code is US: "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" Allowed values When the country code is CA: "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.
ZipCd	String	DBA's ZIP code. 5-16 characters
Country	String	DBA'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"
Address	Object	Primary address of the recipient.
Address1	String	Street address or PO Box of the recipient. Max 46 characters
Address2	String	Optional Suite or apartment number of the recipient. Max 46 characters
City	String	City of the recipient. Max 50 characters
ProvinceOrState	String	Province or state name of the recipient. Allowed values When the country code is US: "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" Allowed values When the country code is CA: "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.
ZipCd	String	ZIP code of the recipient. 5-16 characters
Country	String	2-character country code of the recipient. 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"
DOB	String	Optional Date of Birth of the recipient. Format: MM/DD/YYYY
Email	String	Optional Email address of the recipient. Max 100 characters
Fax	String	Optional Fax number of the recipient. 10 digits
Phone	String	Optional Phone number of the recipient. 10 digits
W9Details	Object	Information specific to W-9 / 1099 recipients.
FedTaxClassification	String	Federal tax classification of the recipient as reported on Form W-9. Allowed values "INDIVIDUAL_OR_SOLE_PROPRIETOR", "SINGLE_MEMBER_LLC_NOT_ELECTED", "SINGLE_MEMBER_LLC_ELECTED", "C_CORPORATION", "S_CORPORATION", "PARTNERSHIP", "TRUST_OR_ESTATE", "LLC_C_CORPORATION", "LLC_S_CORPORATION", "LLC_PARTNERSHIP", "OTHERS"
ExemptPayeeCd	String	Optional Exempt payee code as reported on Form W-9. Allowed values "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13"
FATCACode	String	Optional Exemption from FATCA reporting code as reported on Form W-9. Allowed values "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M"
IsBackupWth	Boolean	When set to TRUE, indicates that the recipient is subject to backup withholding.
W8BenDetails	Object	Information specific to foreign recipients (Form W-8BEN).
CitizenOfCountry	String	Country of citizenship of the recipient. 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"
FTIN	String	Optional Foreign Tax Identification Number of the recipient.
IsFTINNotLegallyRequired	Boolean	When set to TRUE, indicates that the recipient is not legally required to provide an FTIN.
1042SDetails	Object	Information specific to 1042-S filings.
Ch3Cd	String	Chapter 3 status code of the recipient. Allowed values "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "35", "36", "37", "38", "39"
Ch4Cd	String	Chapter 4 status code of the recipient. Federal tax classification of the recipient as reported on Form. Allowed values "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "50"
GIIN	String	Optional Recipient's Global Intermediary Identification Number (GIIN). Max 15 characters
LOBCode	String	Optional Limitation on Benefits (LOB) code claimed by the recipient. Allowed values "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12"

Response Body

Field	Type	Description
SuccessRecipients	Object []	Recipient records that were updated successfully.
SequenceId	String	A unique reference ID for the submission that can be used to identify a particular record.
RecipientId	GUID	Unique identifier generated by TaxBandits. Store this for use in all subsequent requests.
PayeeRef	String	Your unique identifier for the recipient, as provided in the request.
Last4DigitTIN	String	Last 4 digits of the recipient TIN, for verification.
IsActive	Boolean	Confirms whether this recipient is currently active.
DBADetails	Object	DBA details of the recipient.
SequenceId	String	A unique reference ID for the submission that can be used to identify a particular DBA.
DBAId	GUID	TaxBandits-generated unique identifier for the DBA.
DBARef	String	Your unique identifier for the DBA.
DBANm	String	Name of the DBA as registered.
ErrorRecipients	Object []	Records that failed, with details on why.
SequenceId	String	A unique reference ID for the submission that can be used to identify a particular DBA.
RecipientId	GUID	Recipient identifier if a partial record was updated.
PayeeRef	String	Your unique identifier for the recipient.
Last4DigitTIN	String	Last 4 digits of the TIN for reference.
Errors	Object []	Validation error details.
Id	String	Validation error code.
Name	String	Name of the validation rule that failed.
Message	String	Clear description of what went wrong and how to fix it.
Errors	Object []	Top-level request errors if the entire request cannot be processed.
Id	String	Validation error code.
Name	String	Name of the validation rule that failed.
Message	String	Clear description of what went wrong and how to fix it.

Request JSON

{
    "Recipients": [
        {
            "SequenceId": "001",
            "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
            "PayeeRef": "PAYEE001",
            "TINDetails": {
                "Format": "PLAIN_TIN",
                "TINType": "SSN",
                "TIN": "123-45-6000"
            },
            "IndividualNm": {
                "FirstNm": "John",
                "MiddleNm": "Michael",
                "LastNm": "Smith",
                "Suffix": null
            },
            "NameCtrl": null,
            "BusinessNm": null,
            "DBADetails": {
                "DBANm": "Smith Consulting",
                "DBARef": "SC001",
                "DBAId": "a32b351f-00b6-4639-a1ec-835b10ee8dae",
                "Address": {
                    "Address1": "4500 N Lamar Blvd",
                    "Address2": "Suite 210",
                    "City": "Austin",
                    "ProvinceOrState": "TX",
                    "ZipCd": "78756",
                    "Country": "US"
                }
            },
            "Address": {
                "Address1": "123 Main Street",
                "Address2": "Apt 4B",
                "City": "Austin",
                "ProvinceOrState": "TX",
                "ZipCd": "78701",
                "Country": "US"
            },
            "DOB": "01/05/1970",
            "Email": "john.smith@example.com",
            "Fax": null,
            "Phone": "(512) 555-1234",
            "W9Details": {
                "FedTaxClassification": "INDIVIDUAL_OR_SOLE_PROPRIETOR",
                "ExemptPayeeCd": null,
                "FATCACode": null,
                "IsBackupWth": false
            },
            "W8BenDetails": null,
            "Form1042SDetails": null
        }
    ]
}

Response JSON

{
    "StatusCode": 200,
    "SuccessRecipients": [
        {
            "SequenceId": "001",
            "RecipientId": "d67539c3-0603-4fb7-9a29-3ae15339269a",
            "PayeeRef": "PAYEE001",
            "Last4DigitTIN": "6000",
            "DBADetails": {
                "DBANm": "Smith Consulting",
                "DBARef": "SC001",
                "DBAId": "a32b351f-00b6-4639-a1ec-835b10ee8dae"
            }
        }
    ],
    "ErrorRecipients": null,
    "Errors": null
}

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

Key Points​

Request Body

Response Body

Request JSON​

Response JSON​

Key Points

Request JSON

Response JSON