Skip to main content
Version: 2.0.0

Create

Create

Use this endpoint to create a new recipient (vendors, contractors, or other payees) for whom you'll be filing tax forms in the TaxBandits API. Pass all required recipient details in the request body.

Upon successful request, TaxBandits returns a unique RecipientId that you can use in subsequent API requests — no need to pass the full recipient details each time.

Multiple recipients can be created in a single request by passing multiple objects in the Recipients array.

Key Points​

  • PayeeRef — You can assign your own identifier to each recipient. Once set, PayeeRef can be used in place of RecipientId across all endpoints.
  • SSN vs EIN — If the recipient TIN type is SSN/ITIN/ATIN, provide IndividualNm (FirstNm, LastNm) instead of BusinessNm, per IRS requirements.
  • TIN Security — To avoid transmitting raw TINs, use ENCRYPTED or TOKEN as the Format. Raw TINs are only required when Format is PLAIN_TIN.
  • DBA at Creation — A DBA (Doing Business As) name can be included at the time of recipient creation. Additional DBAs can be added later using the AddDBA endpoint.
  • Form-Specific Fields — W9Details is used for W-9/1099 recipients. W8BenDetails is used for foreign recipients (Form W-8BEN). 1042SDetails is required for 1042-S filings.

For descriptions of supported ENUM values, check out the ENUM reference.

POST recipient/create
Run in Postman

Request Body

FieldTypeDescription
RecipientsObject []An array of recipient objects. Pass multiple objects to create 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
   PayeeRefStringOptional Your unique identifier for the recipient. Can replace RecipientId in future requests.
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", "ATIN", "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.
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 created or 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 created.
   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
Creates a recipient (payee) using a plain SSN along with an individual name, address, and contact details.
Sample 2
Creates a recipient using a plain EIN with a business name instead of an individual.
Sample 3
Creates a recipient using a tokenized TIN (masked/secure format) instead of the plain SSN value.
Sample 4
Creates a recipient configured for W-9 collection, including DBA details, date of birth, and W9-specific fields (federal tax classification, exempt payee code, FATCA code, backup withholding flag).
Sample 5
Creates a foreign recipient configured for W-8BEN purposes, including citizenship country, foreign TIN (FTIN), and whether an FTIN is legally required.
Sample 6
Creates a recipient configured for 1042-S reporting, combining W8BEN details (citizenship, FTIN) with 1042-S specific fields (Chapter 3/4 codes, GIIN, LOB code) for foreign-person income reporting.
Sample 7
Creates multiple recipients in a single request, demonstrating support for "NA" (no TIN) and ITIN TIN types across different countries (Canada, UK). Showcases batch recipient creation with varied TIN scenarios.
Sample 1
{
  "Recipients": [
    {
      "SequenceId": "001",
      "PayeeRef": "PAYEE-001",
      "TINDetails": {
        "Format": "PLAIN_TIN",
        "TINType": "SSN",
        "TIN": "321-45-5780"
      },
      "IndividualNm": {
        "FirstNm": "David",
        "MiddleNm": "R",
        "LastNm": "Thompson",
        "Suffix": "Jr"
      },
      "BusinessNm": null,
      "DBADetails": null,
      "Address": {
        "Address1": "1450 Oak Lawn Avenue",
        "Address2": "Apt 310",
        "City": "Dallas",
        "ProvinceOrState": "TX",
        "ZipCd": "75207",
        "Country": "US"
      },
      "DOB": null,
      "Email": "david.thompson@example.com",
      "Fax": "9725550199",
      "Phone": "9725550100"
    }
  ]
}
Response Json
SampleDescriptionAction
200
Success Response - This is a sample response for successful API requests.
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": "4d24c6e3-a1ad-4ae7-bbd6-75b5b63ec96a",
      "PayeeRef": "PAYEE-001",
      "Last4DigitTIN": "5780",
      "DBADetails": {
        "DBANm": "Thompson Financial Services",
        "DBARef": "DBA-PAYEE-001",
        "DBAId": "00a397d3-0b5f-47fb-9a74-8b54041f6c69"
      }
    }
  ],
  "ErrorRecipients": null,
  "Errors": null
}