Create

Use this endpoint to add a new business to TaxBandits.

In the request JSON, you can provide a unique identifier for the business, i.e., PayerRef. Furthermore, the response to this API request will provide you with another unique identifier, i.e., ‘BusinessId’. You can either use PayerRef or BusinessId in your future API requests related to the business.

For the description of ENUM values, Click Here.

According to the recent IRS update for 2024, for businesses with SSNs, you must provide the name using the ‘FirstNm’, ‘MiddleNm’, ‘LastNm’, and ‘Suffix’ nodes instead of ‘BusinessNm’.

note

If you prefer to set the business as default, you must set the ‘IsDefaultBusiness’ node as True.

POST Business/Create 

Request Body

Field	Type	Description
BusinessNm	string	Name of the business. Size Range: ..75
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"
PayerRef	String	Optional An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API. Size Range: 1-50
TradeNm	string	Optional Name under which the business operates Size Range: ..75
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	string	When IsEIN is true, use Employer Identification Number (EIN). When IsEIN is false, use Social Security Number (SSN) Size Range: 9-11
IsDefaultBusiness	Boolean	When set true, this business will be set as the default business.
Email	string	Optional Email address of the Business Size Range: ..100
ContactNm	string	Optional Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Optional Contact number of the business with area code Size Range: 10
PhoneExtn	string	Optional Extension number of the business phone number Size Range: ..5
Fax	string	Optional Fax number of the Business Size Range: 10
BusinessType	string	Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: ..4 Allowed values "ESTE", "PART", "CORP", "EORG", "SPRO" For the description of the Allowed Values , click here
SigningAuthority	object	Details of the person who is authorized to sign the return.
Name	string	Optional Name of the signing authority. Size Range: ..75
Phone	string	Optional Phone number of the authorized signatory. Size Range: 10
BusinessMemberType	string	Optional Business title of the authorized signatory. Size Range: 5..29 Allowed values "CORPORATESECRETARY", "SECRETARYTREASURER", "PARTNER", "GENERALPARTNER", "LIMITEDPARTNER", "LLCMEMBER", "MANAGINGMEMBER", "MANAGER", "TAXMATTERPARTNER", "PRESIDENT", "VICEPRESIDENT", "CORPORATETREASURER", "TREASURER", "ASSISTANTTREASURER", "CHIEFACCOUNTINGOFFICER", "CHIEFEXECUTIVEOFFICER", "CHIEFFINANCIALOFFICER", "TAXOFFICER", "CHIEFOPERATINGOFFICER", "CORPORATEOFFICER", "EXECUTIVEDIRECTOR", "DIRECTOR", "CHAIRMAN", "EXECUTIVEADMINISTRATOR", "RECEIVER", "PASTOR", "ASSISTANTTORELIGIOUSLEADER", "REVEREND", "PRIEST", "MINISTER", "RABBI", "LEADEROFRELIGIOUSORGANIZATION", "SECRETARY", "DIRECTOROFTAXATION", "DIRECTOROFPERSONNEL", "ADMINISTRATOR", "EXECUTOR", "TRUSTEE", "FIDUCIARY", "OWNER", "SOLEPROPRIETOR", "MEMBER", "SOLEMEMBER"
KindOfEmployer	string	Identifies the kind of employer. Mandatory for W-2 and optional for 1099-MISC and 94X series Allowed values "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	Identifies the kind of payer. Mandatory for W-2 and optional for 1099-MISC and 94X series Allowed values "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
Form1042SDetails	object	Chapter 3 and chapter 4 status code details of the busienss. Mandatory for 1042-S and optional for 1099 and 94X series
WHAgtCh3Cd	string	Chapter 3 status code of Withholding agent Size Range: 2 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"
WHAgtCh4Cd	string	Chapter 4 status code of Withholding agent Size Range: 2 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"
WHAgtGIIN	string	Optional Withholding agent’s Global Intermediary Identification Number (GIIN) Size Range: ..15
FTIN	string	Optional FTIN of Withholding agent
Country	string	Optional Withholding agent's country 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"
IsForeign	Boolean	When true, identifies the business address with a foreign address.
USAddress	object	if IsForeign is false, pass US address of the business
Address1	string	Address of the Employer/Payer (street address or post office box of that locality) Size Range: ..46
Address2	string	Optional Suite or apartment number of the Employer/Payer. Size Range: ..46
City	string	City where the Employer/Payer is based out of Size Range: ..50
State	string	Name of the state where the Employer/Payer is based out of 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	Zip Code the State where the Employer/Payer is based out of. Size Range: 5..10
ForeignAddress	object	if IsForeign is true, pass foreign address of the business.
Address1	string	Address of the Employer/Payer (street address or post office box of that locality) Size Range: ..50
Address2	string	Optional Suite or apartment number of the Employer/Payer. Size Range: ..50
City	string	City where the Employer/Payer is based out of Size Range: ..50
ProvinceOrStateNm	string	Name of the province or state where the Employer/Payer is based out of. Size Range: ..50
Country	string	Country of the Employer/Payer. 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	Postal Code the State where the Employer/Payer is based out of Size Range: ..16
ACADetails	object	Contains specific field information for ACA forms
FirstName	string	First Name of the contact person. Size Range: 50
MiddleName	string	Optional Middle initials of the contact person. Size Range: 15
LastName	string	Last name of the contact person. Size Range: 50
Suffix	string	Optional Name suffix of the contact person. Refer static values. Size Range: 3 Allowed values "JR", "SR", "II", "III", "IV", "V", "VI", "VII"
Phone	string	Phone number of the government entity's contact person. Size Range: 10
IsGovernmentalUnit	boolean	When true, identifies that the business is a part of or related to the Governmental Unit

Response Body

Field	Type	Description
StatusCode	number	Returns the status codes like 200, 300 etc.
StatusName	string	Name of the status code.
StatusMessage	string	Detailed status message
BusinessId	Guid	Unique Identifier of the business
PayerRef	string	Unique identifier of the payer.
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	string	Employer Identification Number (EIN) or Social Security Number (SSN)
BusinessNm	string	Name of the business
FirstNm	string	First Name of the Individual
MiddleNm	string	Middle Name of the Individual
LastNm	string	Last Name of the Individual
Suffix	string	Suffix of the Individual
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 business using EIN and Business name. This should be the default business.
Sample 2	Create a business using SSN and name.
Sample 3	Create a business using only EIN.

Sample 1

{
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "MiddleNm": null,
    "LastNm": null,
    "Suffix": null,
    "PayerRef": "Snow123",
    "TradeNm": "Iceberg Icecreams",
    "IsDefaultBusiness": true,
    "IsEIN": true,   
    "EINorSSN": "23-3456789",
    "Email": "james@sample.com",
    "ContactNm": "James Smith",
    "Phone": "6534567890",
    "PhoneExtn": "123",
    "Fax": "9834567890",
    "BusinessType": "ESTE",
    "SigningAuthority": {
        "Name": "James Smith",
        "Phone": "9934567890",
        "BusinessMemberType": "ADMINISTRATOR"
    },
    "KindOfEmployer": "FEDERALGOVT",
    "KindOfPayer": "REGULAR941",
    "IsBusinessTerminated": false,
    "Form1042SDetails": {
      "WHAgtCh3Cd": "11",
      "WHAgtCh4Cd": "16",
      "WHAgtGIIN": null,
      "FTIN": "12345",
      "Country": "AL"
    },
    "IsForeign": false,
    "USAddress": {
        "Address1": "3576 AIRPORT WAY",
        "Address2": "UNIT 9",
        "City": "FAIRBANKS",
        "State": "AK",
        "ZipCd": "99709"
    },
    "ForeignAddress": null,
    "ACADetails": {
      "FirstName": "Kingston",
      "MiddleName": "Walman",
      "LastName": "ADMINRATOR",
      "Suffix": "Jr",
      "Phone": "8834578906",
      "IsGovernmentalUnit": true
    }
}

Response Json

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

{
    "StatusCode": 200,
    "StatusName": "Ok",
    "StatusMessage": "Successful API call",
    "BusinessId": "519a84f4-5e56-496a-82f3-18f51fdf3d75",
    "PayerRef": "Snow123",
    "IsEIN": true,
    "EINorSSN": "XX-XXX6789",
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "LastNm": null,
    "MiddleNm": null,
    "Suffix": null,
    "Errors": null
}

Node.js

Python

Java

.NET C#