Skip to main content
Version: 1.7.1

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
Run in Postman

Request Body

FieldTypeDescription
BusinessInfoobjectObject to identify the Business Details.
    BusinessIdGuidOptional Use the unique Business ID (Generated by TaxBandits), you received in the response of the Business CREATE Endpoint.
    PayerRefstringOptional 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
    TINstringEnter the nine-digit taxpayer identification number of the business (SSN,EIN).
Size Range:9
    TINTypestringSpecify the TIN type of the business.
Allowed values

"SSN", "EIN"

Recipientobject[]Object to identify the recipient details.
    TINTypestringSpecify the TIN type of the recipient.
Allowed values

"SSN", "EIN", "ITIN", "ATIN", "NA"

    TINstringEnter the nine-digit taxpayer identification number of the Recipient (SSN, ITIN, ATIN, or EIN).
Size Range: 9
    PayeeRefstringOptional 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
    FirstPayeeNmstringEnter 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
    SecondPayeeNmstringOptional 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
    FirstNmstringFirst Name of the Individual
Size Range: ..20
    MiddleNmstringMiddle Name of the Individual
Size Range: ..20
    LastNmstringLast Name of the Individual
Size Range: ..20
    SuffixstringSuffix of the Individual
Allowed values

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

    IsForeignBooleanWhen true, identify the recipient address with a foreign address.
    USAddressobjectIf IsForeign is false, pass the US address of the recipient
       Address1stringRecipient's US address (street address or post office box of that locality)
Size Range: ..46
       Address2stringOptional Recipient's suite or apartment
Size Range: ..46
       CitystringRecipient's city
Size Range: ..50
        StatestringRecipient'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"

       ZipCdstringRecipient's zip code
Size Range: 5..10
    ForeignAddressobjectIf IsForeign is true, pass the foreign address of the recipient
        Address1stringRecipient's foreign address (street address or post office box of that locality)
Size Range: ..50
        Address2stringOptional Recipient's suite or apartment
Size Range: ..50
        CitystringRecipient's city.
Size Range: ..50
        ProvinceOrStateNmstringRecipient's Province or State Name.
Size Range: ..50
        CountrystringRecipient'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"

        PostalCdstringRecipient's Postal Code.
Size Range: ..16
    EmailstringOptional Recipient's email address.
Size Range: 0..100
    FaxstringOptional Recipient's Fax number.
Size Range: 10
    PhonestringOptional Recipient's Phone Number.
Size Range: 10

Request JSON

Create a recipient with TINTYPE EIN

{
    "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 801",
                "City": "Toronto",
                "ProvinceOrStateNm": "Ontario",
                "Country": "IN",
                "PostalCd": "4168682600"
            },
            "Email": "shawn@sample.com",
            "Fax": "6634567890",
            "Phone": "9634567890"
        }
    ]
}

Response Body

FieldTypeDescription
BusinessobjectObject to identify the Business Details.
    BusinessIdGuidOptional 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.
    PayerRefstringOptional 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
    BusinessNmstringName of the business.
Size Range: ..75
    TINTypestringSpecify the TIN type of the business.
Allowed values

"SSN", "EIN"

    TINstringEnter the nine-digit taxpayer identification number of the business (SSN,EIN).
Size Range: 9
Recipientobject[]Object to identify the recipient details.
   SuccessRecipientobjectIt will show detailed information about the success status of Recipient Records
        RecipientIdGuidA unique identifier generated by TaxBandits for a Recipient. You can use this ID for your future reference to Update.
        TINTypestringReturns the TIN type of the recipient.
        TINstringReturns the TIN of the recipient.
        PayeeRefstringA unique identifier for each payee completing their information.
        FirstPayeeNmstringReturns the name of the recipient.
        SecondPayeeNmstringReturns the name of the second recipient.
        FirstNmstringFirst Name of the Individual
Size Range: ..20
        MiddleNmstringMiddle Name of the Individual
Size Range: ..20
        LastNmstringLast Name of the Individual
Size Range: ..20
        SuffixstringSuffix of the Individual
Allowed values

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

    ErrorRecipientobject[]It will show detailed information about the error status of Recipient Records.
Errorsobject[]Shows detailed error information.
    IdstringReturns the validation error Id.
    NamestringName of the validation error.
    MessagestringDescription of the validation error.

Response JSON

Success Response - This is a sample response for successful API requests.

{
    "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
}