Version: 2.0

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

Field	Type	Description
Recipients	Object []	An array of recipient objects. Pass multiple objects to create 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
PayeeRef	String	Optional Your unique identifier for the recipient. Can replace `RecipientId` in future requests. 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. 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 created or 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 created.
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",
            "PayeeRef": "PAYEE001",
            "TINDetails": {
                "Format": "PLAIN_TIN",
                "TINType": "SSN",
                "TIN": "123-45-6000"
            },
            "IndividualNm": {
                "FirstNm": "John",
                "MiddleNm": "Michael",
                "LastNm": "Smith",
                "Suffix": null
            },
            "BusinessNm": null,
            "DBADetails": {
                "DBANm": "Smith Consulting",
                "DBARef": "SC001",
                "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": "5125551234",
            "W9Details": {
                "FedTaxClassification": "INDIVIDUAL_OR_SOLE_PROPRIETOR",
                "ExemptPayeeCd": null,
                "FATCACode": null,
                "IsBackupWth": false
            },
            "W8BenDetails": {
                "CitizenOfCountry": null,
                "FTIN": null,
                "IsFTINNotLegallyRequired": null
            },
            "1042SDetails": {
                "Ch3Cd": null,
                "Ch4Cd": null,
                "GIIN": null,
                "LOBCode": 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

Create

Create

Key Points​

Request Body

Response Body

Request JSON​

Response JSON​

Key Points

Request JSON

Response JSON