Create

Use this endpoint to add a new recipient to TaxBandits.

In the request JSON, you can provide a unique identifier for the recipient, i.e., PayeeRef. Furthermore, the response to this API request will provide you with another unique identifier, i.e., ‘RecipientId’.

POST Recipient/Create

Request Body

Field	Type	Description
BusinessInfo	object	Object to identify the Business Details.
BusinessId	Guid	Optional Use the unique Business ID (Generated by TaxBandits), you received in the response of the Business CREATE Endpoint.
PayerRef	string	Optional A unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API. Size Range: ..50
TIN	string	Enter the nine-digit taxpayer identification number of the business (SSN,EIN). Size Range:9
TINType	string	Specify the TIN type of the business. Allowed values "SSN", "EIN"
Recipient	object[]	Object to identify the recipient details.
TINType	string	Specify the TIN type of the recipient. Allowed values "SSN", "EIN", "ITIN", "ATIN", "NA"
TIN	string	Enter the nine-digit taxpayer identification number of the Recipient (SSN, ITIN, ATIN, or EIN). Size Range: 9
PayeeRef	string	Optional A unique identifier for each payee completing their information. This identifier can be used in future references of the payee in the API. Size Range: ..50
FirstPayeeNm	string	Enter the name of the recipient (preferably last name first for an Individual). If more space is required for the name, use the Second Payee Name Field. Size Range: 40
SecondPayeeNm	string	Optional If there are multiple recipients (for example, partners, joint owners, or spouses), use this field for those names not associated with the TIN or if not enough space was provided in the First Payee Name, continue the name in this field. Size Range: 40
FirstNm	string	First Name of the Individual Size Range: ..20
MiddleNm	string	Middle Name of the Individual Size Range: ..20
LastNm	string	Last Name of the Individual Size Range: ..20
Suffix	string	Suffix of the Individual Allowed values "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
IsForeign	Boolean	When true, identify the recipient address with a foreign address.
USAddress	object	If IsForeign is false, pass the US address of the recipient
Address1	string	Recipient's US address (street address or post office box of that locality) Size Range: ..46
Address2	string	Optional Recipient's suite or apartment Size Range: ..46
City	string	Recipient's city Size Range: ..50
State	string	Recipient's state code. Refer Static values. 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	Recipient's zip code Size Range: 5..10
ForeignAddress	object	If IsForeign is true, pass the foreign address of the recipient
Address1	string	Recipient's foreign address (street address or post office box of that locality) Size Range: ..50
Address2	string	Optional Recipient's suite or apartment Size Range: ..50
City	string	Recipient's city. Size Range: ..50
ProvinceOrStateNm	string	Recipient's Province or State Name. Size Range: ..50
Country	string	Recipient's country code. Refer Static values. 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	Recipient's Postal Code. Size Range: ..16
Email	string	Optional Recipient's email address. Size Range: 0..100
Fax	string	Optional Recipient's Fax number. Size Range: 10
Phone	string	Optional Recipient's Phone Number. Size Range: 10

Response Body

Field	Type	Description
Business	object	Object to identify the Business Details.
BusinessId	Guid	Optional Use the unique Business ID (Generated by TaxBandits), you received in the response of the Business CREATE Endpoint. If you do not have a Business ID, ignore the field. By giving the Business ID, you do not have to provide all the business information again.
PayerRef	string	Optional A unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API. Size Range: ..50
BusinessNm	string	Name of the business. Size Range: ..75
TINType	string	Specify the TIN type of the business. Allowed values "SSN", "EIN"
TIN	string	Enter the nine-digit taxpayer identification number of the business (SSN,EIN). Size Range: 9
Recipient	object[]	Object to identify the recipient details.
SuccessRecipient	object	It will show detailed information about the success status of Recipient Records
RecipientId	Guid	A unique identifier generated by TaxBandits for a Recipient. You can use this ID for your future reference to Update.
TINType	string	Returns the TIN type of the recipient.
TIN	string	Returns the TIN of the recipient.
PayeeRef	string	A unique identifier for each payee completing their information.
FirstPayeeNm	string	Returns the name of the recipient.
SecondPayeeNm	string	Returns the name of the second recipient.
FirstNm	string	First Name of the Individual Size Range: ..20
MiddleNm	string	Middle Name of the Individual Size Range: ..20
LastNm	string	Last Name of the Individual Size Range: ..20
Suffix	string	Suffix of the Individual Allowed values "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
ErrorRecipient	object[]	It will show detailed information about the error status of Recipient Records.
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.

Payload

Request Json

Sample	Description	Action
Sample 1	Create a recipient with TINTYPE EIN
Sample 2	Create a recipient with TINTYPE SSN
Sample 3	Create multiple recipient

Sample 1

{
    "BusinessInfo": {
       "BusinessId": "b073763e-13d6-43c6-b849-9d0975851939",
        "BusinessNm": "Snowdaze LLC",
        "PayerRef": null,
        "TIN": "003313330",
        "TINType": "EIN"
    },
    "Recipient": [
        {
            "RecipientId": null,
            "TINType": "EIN",
            "TIN": "387559984",
            "PayeeRef":null,
            "FirstPayeeNm": "Dairy Delights LLC",
            "SecondPayeeNm": "Coco Milk",
            "FirstNm":null,
            "LastNm":null,
            "MiddleNm" : null,
            "Suffix":null,
            "IsForeign": true,
            "USAddress": null,
            "ForeignAddress": {
                "Address1": "120 Bremner Blvd",
                "Address2": "Suite 800",
                "City": "Toronto",
                "ProvinceOrStateNm": "Ontario",
                "Country": "IN",
                "PostalCd": "4168682600"
            },
            "Email": "shawn@sample.com",
            "Fax": "6634567890",
            "Phone": "9634567890"
        }
    ]
}

Response Json

Response	Description	Action
200	Success Response - This is a sample response for successful API requests.
300	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

{
    "Business": {
        "BusinessId": "b073763e-13d6-43c6-b849-9d0975851939",
        "PayerRef": "Pay123",
        "BusinessNm": "Snowdaze LLC",
        "FirstNm": null,
        "LastNm": null,
        "MiddleNm": null,
        "Suffix": null,
        "TINType": "EIN",
        "TIN": "32-3313330"
    },
    "Recipient": {
        "SuccessRecipient": [
            {
                "RecipientId": "4417e993-5ba9-47fb-9b44-b3ac902ea61d",
                "TINType": "EIN",
                "TIN": "38-7559984",
                "PayeeRef": null,
                "FirstPayeeNm": "Dairy Delights LLC",
                "SecondPayeeNm": "Coco Milk",
                "FirstNm": null,
                "LastNm": null,
                "MiddleNm": null,
                "Suffix": null
            }
        ],
        "ErrorRecipient": null
    },
    "Errors": null
}

Node.js

Python

Java

.NET C#