Skip to main content
Version: 2.0.0

Update

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, TOKENIZED_TIN) 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

FieldTypeDescription
Recipientsobject []An array of recipient objects. Pass multiple objects to update recipients in bulk.
   SequenceIdStringOptional 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
   RecipientIdGUIDTaxBandits-generated unique identifier for the recipient. Required if PayeeRef is not provided.
   PayeeRefstringOptional Your unique identifier for the recipient. Required if RecipientId is not provided.
Max 50 characters
   TINDetailsObjectTIN information for the recipient
      FormatStringSpecifies how the TIN is passed.
Allowed values

"PLAIN_TIN" — Pass TIN directly.
"TOKENIZED_TIN" - Pass tokenized TIN.

      TINTypestringSpecify the TIN type of the recipient.
Allowed values

"EIN", "SSN", “AIN”, “ITIN”, “QI-EIN”, “WP-EIN”, “WT-EIN”, “NQI-EIN”, “NA”

      TINstringThe TIN value, formatted according to the Format field selected.
   IndividualNmObjectRequired when TINType is SSN, ITIN, or ATIN. Provide individual name fields instead of BusinessNm.
      FirstNmStringThe first name of the individual.
Max 20 characters
      MiddleNmStringOptional The middle name of the individual.
Max 20 characters
      LastNmStringThe last name of the individual.
Max 20 characters
      SuffixStringOptional The suffix of the individual's name.
Allowed values

"Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"

   BusinessNmStringLegal name of the recipient business. Required when TINType is EIN.
Max 75 characters
   DBADetailsObjectOptional DBA (Doing Business As) information. Optional at creation - additional DBAs can be added later via AddDBA.
      DBANmStringName of the DBA.
Max 75 characters
      DBARefStringYour unique identifier for this DBA.
1-50 characters
      DBAIdGUIDTaxBandits-generated DBA identifier. Returned in the response.
      AddressObjectAddress information of DBA.
         Address1StringStreet address or PO Box.
Max 46 characters
         Address2StringOptional Suite or apartment number.
Max 46 characters
         CityStringDBA's city.
Max 50 characters
         ProvinceOrStateStringDBA'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.
         ZipCdStringDBA's ZIP code.
5-16 characters
         CountryStringDBA'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"

   AddressObjectPrimary address of the recipient.
      Address1StringStreet address or PO Box of the recipient.
Max 46 characters
      Address2StringOptional Suite or apartment number of the recipient.
Max 46 characters
      CityStringCity of the recipient.
Max 50 characters
      ProvinceOrStateStringProvince 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.
      ZipCdStringZIP code of the recipient.
5-16 characters
      CountryString2-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"

   DOBStringOptional Date of Birth of the recipient. Format: MM/DD/YYYY
   EmailStringOptional Email address of the recipient.
Max 100 characters
   FaxStringOptional Fax number of the recipient.
10 digits
   PhoneStringOptional Phone number of the recipient.
10 digits
   W9DetailsObjectInformation specific to W-9 / 1099 recipients.
      FedTaxClassificationStringFederal 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"

      ExemptPayeeCdStringOptional Exempt payee code as reported on Form W-9.
Allowed values

"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13"

      FATCACodeStringOptional 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"

      IsBackupWthBooleanWhen set to TRUE, indicates that the recipient is subject to backup withholding.
   W8BenDetailsObjectInformation specific to foreign recipients (Form W-8BEN).
      CitizenOfCountryStringCountry 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"

      FTINStringOptional Foreign Tax Identification Number of the recipient.
      IsFTINNotLegallyRequiredBooleanWhen set to TRUE, indicates that the recipient is not legally required to provide an FTIN.
   1042SDetailsObjectInformation specific to 1042-S filings.
      Ch3CdStringChapter 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"

      Ch4CdStringChapter 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"

      GIINStringOptional Recipient's Global Intermediary Identification Number (GIIN).
Max 15 characters
      LOBCodeStringOptional Limitation on Benefits (LOB) code claimed by the recipient.
Allowed values

"02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12"

Response Body

FieldTypeDescription
SuccessRecipientsObject []Recipient records that were updated successfully.
   SequenceIdStringA unique reference ID for the submission that can be used to identify a particular record.
   RecipientIdGUIDUnique identifier generated by TaxBandits. Store this for use in all subsequent requests.
   PayeeRefStringYour unique identifier for the recipient, as provided in the request.
   Last4DigitTINStringLast 4 digits of the recipient TIN, for verification.
   IsActiveBooleanConfirms whether this recipient is currently active.
   DBADetailsObjectDBA details of the recipient.
      SequenceIdStringA unique reference ID for the submission that can be used to identify a particular DBA.
      DBAIdGUIDTaxBandits-generated unique identifier for the DBA.
      DBARefStringYour unique identifier for the DBA.
      DBANmStringName of the DBA as registered.
ErrorRecipientsObject []Records that failed, with details on why.
   SequenceIdStringA unique reference ID for the submission that can be used to identify a particular DBA.
   RecipientIdGUIDRecipient identifier if a partial record was updated.
   PayeeRefStringYour unique identifier for the recipient.
   Last4DigitTINStringLast 4 digits of the TIN for reference.
   ErrorsObject []Validation error details.
      IdStringValidation error code.
      NameStringName of the validation rule that failed.
      MessageStringClear description of what went wrong and how to fix it.
ErrorsObject []Top-level request errors if the entire request cannot be processed.
   IdStringValidation error code.
   NameStringName of the validation rule that failed.
   MessageStringClear description of what went wrong and how to fix it.
Request JSON
SampleDescriptionAction
Sample 1
Update a recipient with TIN, DBA, address, contact, and form-specific details.
Sample 1
{
  "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
ResponseDescriptionAction
200
Success Response - You'll get the below response when the request is processed successfully.
207
Multi-status Response - You'll get the below response when multiple statuses are included.
400
Bad Request Response - You'll get the below response when your API requests contain any validation errors.
401
Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.
Response: 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
}