# Form1099NEC

# Approve

If you are using TaxBandits API to send Transactions and then generate 1099s using the transactions data, then this endpoint will be applicable to you. This endpoint is used to approve the draft 1099-NECs generated by TaxBandits. Once the returns are approved you will be able to transmit these 1099-NEC using the Transmit method of the 1099-NEC API.

POST Form1099NEC/Approve

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
RecordIds	Guid[]	List of record Ids to get the Approved Form 1099-NEC.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
Form1099NECRecords	object	Contains Form 1099NEC records that are approved.
SuccessRecords	object[]	Contains detailed information of Form 1099 NECs that were successfully approved.
RecordId	string	Unique identifier of a record
Status	Guid	Status of the 1099-NEC.
StatusTs	Guid	Returns date and time of return created.
ErrorRecords	object[]	Contains the list of errors
PayeeRef	string	Unique identifier of the recipient. Set by the client.
RecipientId	Guid	Unique identifier of the recipient. Generated by TaxBandits.
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
Errors	object[]	Shows the detailed error information
Id	string	Validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
  "SubmissionId": "ed4eb5c4-cc6a-4b34-8253-ac326674fb41",
  "RecordIds": [
      "f53d6303-9d48-4ed8-8d4a-5b6713392e47",
      "7d403f42-3533-41bd-9c9e-c2cb6f1cb365"
  ]
}

1
2
3
4
5
6
7

Response JSON

{
 "SubmissionId": "ed4eb5c4-cc6a-4b34-8253-ac326674fb41",
 "Form1099NECRecords": {
   "SuccessRecords": [
     {
       "RecordId": "f53d6303-9d48-4ed8-8d4a-5b6713392e47",
       "Status": "CREATED",
       "StatusTs": "2021-12-03 03:06:58 -05:00"
     },
     {
       "RecordId": "7d403f42-3533-41bd-9c9e-c2cb6f1cb365",
       "Status": "CREATED",
       "StatusTs": "2021-12-03 03:06:58 -05:00"
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Create

Creates Form 1099-NEC returns in TaxBandits. You can send multiple 1099-NEC forms in a single request for the same Payer. In response, a SubmissionId is created which is further used as a reference for all other methods of Form 1099 NEC API.

POST Form1099NEC/Create

Request Body

Field	Type	Description
SubmissionManifest	object	SubmissionManifest provides the brief information about a particular submission on the whole. It contains information like Submission ID, Tax Year, IsPostal, IsFederalFiling, IsStateFiling, IsOnlineAccess, IsScheduleFiling & ScheduleFiling service details.
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
TaxYear	string	Tax year of Form 1099 NEC to be filed. Allowed values: "2021"
IsFederalFiling	Boolean	Federal Filing for the return will be enabled when the value is True. Form 1099-NEC will be sent directly to the IRS.
IsStateFiling	Boolean	State Filing for the return will be enabled when the value is True. Form 1099-NEC will be directly filed with the respective recipient states. Note: State Filing will not be created for the states that do not require State filing.
IsPostal	Boolean	Postal Order will be created when the value is set as True. Once the return is Transmitted, Form 1099-NEC Recipient copies will be postal mailed to the recipient's address via USPS. Note: Postal Orders for Foreign Address will not be created.
IsOnlineAccess	Boolean	Online Access will be enabled when the value is set as True. Once the return is Transmitted, an email with the link to the secure TaxBandits portal will be sent to the Recipient. The recipient can provide consent and download Form 1099-NEC Recipient copies from the portal.
IsScheduleFiling	Boolean	When true, schedule filing services will be provided for Form 1099 NEC returns under this submission.
ScheduleFiling	object	Contains preferred date to submit the returns to the IRS. Required only when "IsScheduleFiling" is True .
EfileDate	string	Date of Schedule Filing. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY Example: 10/20/2021 or 10-20-2021
ReturnHeader	object	Contains information about the Business details.
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 have 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.
BusinessNm	string	Name of the business Size Range: ..75
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: ..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
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	`Optional` Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Phone number of the business Size Range: 10
PhoneExtn	string	`Optional` Extension of the business phone number Size Range: ..5
Fax	string	`Optional` Fax number of the Business Size Range: 10
BusinessType	string	`Optional` Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: 4 Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
SigningAuthority	object	`Optional` Details of the person who is authorized to sign the return
Name	string	`Optional` Name of the signing authority Size Range: ..35
Phone	string	`Optional` Phone number of the signing authority Size Range: 10
BusinessMemberType	string	`Optional` Business title of the signing authority 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	`Optional` Identifies the kind of employer. Mandatory for W-2 and optional for 1099-NEC and 94X series Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	`Optional` Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-NEC and 94X series Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
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	Employer/Payer's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	Employer/Payer'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	Employer/Payer's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the business
Address1	string	Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer's country Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
ReturnData	object[]	Contains information about the recipient details and Form 1099 NEC details.
SequenceId	string	An 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. Size Range: 50
RecordId	Guid	Unique identifier of a record. Not required when you are creating a return.
Recipient	object	Object to identify the recipient details.
RecipientId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to Update.
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
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.
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.
IsForeign	Boolean	When true, identifies the recipient address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the recipient
Address1	string	Recipient's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city Size Range: ..27
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
ForeignAddress	object	If IsForeign is true, pass foreign address of the recipient
Address1	string	Recipient's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city. Size Range: ..27
ProvinceOrStateNm	string	Recipient's Province or State Name. Size Range: ..30
Country	string	Recipient's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Recipient's Postal Code
Email	string	Recipient's email address. Size Range: 0..40
Fax	string	`Optional` Recipient's Fax number. Size Range: 10
Phone	string	Recipient's Phone Number. Size Range: 10
NECFormData	object	Recipient's Form 1099 NEC information
B1NEC	number	Gets the Nonemployee compensation (NEC) amount of $600 or more. Size Range: 0-9999999999.99
B2IsDirectSales	Boolean	When true, identifies sales of $5,000 or more of consumer products to a person on a buy-sell, deposit commission, or any other commission basis for resale anywhere other than in a permanent retail establishment.Applicable only for Tax year 2021.
B4FedTaxWH	number	Gets the amount of Federal Tax Withheld. Size Range: 0-9999999999.99
IsFATCA	Boolean	When true, identifies a U.S. payer reporting on Form(s) 1099 (including reporting payments on this Form 1099-NEC) to satisfy their foreign financial asset reporting requirement with respect to a U.S. account.Not Applicable for Tax year 2021.
AccountNum	string	Account number of Payer having multiple accounts for a recipient for whom more than one Form 1099-NEC is filed. Size Range: 4..20
Is2ndTINnot	Boolean	When true, identifies a Payer who is notified by the IRS twice within 3 calendar years for providing an incorrect TIN and do not want the IRS to send any more notices.
States	object[]	Contains list of state returns information.
StateCd	string	State Code. 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"
StateIdNum	string	Identification Number of State. Size Range: ..20
StateWH	number	Income tax amount withheld for State . Size Range: 0-9999999999.99
StateIncome	number	Amount of payment for State. Size Range: 0-9999999999.99
StateReconData	object	Collects State Recon fields specific for each state. Click here, for the description of each state specific Recon fields.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a Business.
PayerRef	string	Unique identifier of the payer.
Form1099Type	string	Denotes the type of 1099 form.
Form1099Records	object	Pulls Form 1099 NEC records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form 1099 NEC Records
SequenceId	string	An 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.
RecordId	Guid	An unique identifier generated by TaxBandits when a 1099-NEC return is created.
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient when a 1099-NEC return is created. You can use this id for your future reference to Update.
AccountNum	string	Account number of Payer having multiple accounts for a recipient for whom more than one Form 1099-NEC is filed. Size Range: 4..20
FederalReturn	object	Returns the record status and StatusTs of federal return.
Status	string	Returns the record status.
StatusTs	string	Returns date and time of return created.
Info	string	Returns information about the Federal Filing service.
StateReturns	object[]	Returns collection of state returns information
StateCd	string	Returns the state code of the state for which the return is filed.
Status	string	Returns the record status of the state return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the state for which we are not supporting state filing.
Errors	object[]	Shows error information of state returns of Form 1099 NEC
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
Postal	object	Returns the status and StatusTs of postal mailing service for Form 1099 NEC.
Status	string	Returns the status of postal order.
StatusTs	string	Returns the date and time of the postal order created.
Info	string	Returns the information about Postal mailing service.
OnlineAccess	object	Returns the Email address for whom the online access to be given and Status of online access.
Status	string	Returns status of online access for Form 1099 NEC return.
Email	string	Email address for whom the online access to be given.
Info	string	Information about the online access service.
ScheduleFiling	object	Returns the date of the schedule filing.
ScheduledOn	string	Date of the schedule filing to know when the return to be filed to the IRS.
Info	string	Information about Schedule Filing service.
ErrorRecords	object[]	It will show the detailed information about the error status of Form 1099 NEC Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
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
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

Request JSON

{
  "SubmissionManifest": {
    "SubmissionId": null,
    "TaxYear": "2021",
    "IsFederalFiling": true,
    "IsStateFiling": true,
    "IsPostal": true,
    "IsOnlineAccess": true,
    "IsScheduleFiling": true,
    "ScheduleFiling": {
      "EfileDate": "12/12/2021"
    }
  },
  "ReturnHeader": {
    "Business": {
      "BusinessId": null,
      "BusinessNm": "Eastman Kodak Com",
      "PayerRef": "Pe123",
      "TradeNm": "Kodak",
      "IsEIN": true,
      "EINorSSN": "62-7369245",
      "Email": "john@gmail.com",
      "ContactNm": "John",
      "Phone": "1234567890",
      "PhoneExtn": "12345",
      "Fax": "1234567890",
      "BusinessType": "ESTE",
      "SigningAuthority": {
        "Name": "John",
        "Phone": "1234567890",
        "BusinessMemberType": "ADMINISTRATOR"
      },
      "KindOfEmployer": "FederalGovt",
      "KindOfPayer": "REGULAR941",
      "IsBusinessTerminated": true,
      "IsForeign": false,
      "USAddress": {
        "Address1": "1751 Kinsey Rd",
        "Address2": "Main St",
        "City": "Dothan",
        "State": "AL",
        "ZipCd": "36303"
      },
      "ForeignAddress": {
        "Address1": null,
        "Address2": null,
        "City": null,
        "ProvinceOrStateNm": null,
        "Country": null,
        "PostalCd": null
      }
    }
  },
  "ReturnData": [
    {
      "RecordId": null,
      "SequenceId": "1",
      "Recipient": {
        "RecipientId": null,
        "TINType": "EIN",
        "TIN": "393817572",
        "FirstPayeeNm": "Mark",
        "SecondPayeeNm": "Davis",
        "IsForeign": false,
        "USAddress": {
          "Address1": "1751 Kinsey Rd",
          "Address2": "Main St",
          "City": "Dothan",
          "State": "AL",
          "ZipCd": "36303"
        },
        "ForeignAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "ProvinceOrStateNm": null,
          "Country": null,
          "PostalCd": null
        },
        "Email": "john@gmail.com",
        "Fax": "1234567890",
        "Phone": "1234567890"
      },
      "NECFormData": {
        "B1NEC": 100,
        "B2IsDirectSales": true,
        "B4FedTaxWH": 40.55,
        "IsFATCA": false,
        "Is2ndTINnot": true,
        "AccountNum": "20123130000009000001",
        "States": [
          {
            "StateCd": "WV",
            "StateWH": 257.94,
            "StateIdNum": "99999999",
            "StateIncome": 2900
          },
          {
            "StateCd": "ID",
            "StateWH": 15,
            "StateIdNum": "999999999",
            "StateIncome": 16
          }
        ]
      }
    }
  ],
  "StateReconData": {
    "WV": {
      "FormIT103": {
        "WVWithHoldingID": "99999998",
        "NumOf1099W2": 24,
        "TotalTaxWH1099W2": 404,
        "WHTaxDue": {
          "WVTaxQ1": 101,
          "WVTaxQ2": 101,
          "WVTaxQ3": 101,
          "WVTaxQ4": 101,
          "TotalForYear": 404
        }
      }
    },
    "ID": {
      "Form967": {
        "IDWithholdingID": "999999999",
        "TotWagesW2": 0,
        "TotTaxWHW2": 200,
        "NumOfW2Forms": 0,
        "TotTaxWH1099": 400,
        "NumOf1099Forms": 40,
        "TotNumOf1099W2": 40,
        "NumOf1099WithWH": 30,
        "TotTaxWH": 600,
        "WHTaxPaid": 500,
        "BalanceDue": 100,
        "Overpayment": 0,
        "PenaltyOnBalanceDue": 100,
        "InterestOnBalanceDue": 100,
        "BalanceDuePenaltyInt": 300,
        "LateFilingPenalty": 200,
        "TotBalanceDue": 500,
        "TotOverPayment": 0,
        "Is1099CFSF": true,
        "FilingCycle": "Annual"
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

Response JSON

{
  "StatusCode": 200,
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "e88e7f1d-7ae5-43b6-99f6-38d85664035a",
  "BusinessId": "c21df64f-9a6d-4e21-ac67-723aacf1ba48",
  "PayerRef": "Pe123",
  "Form1099Type": "NEC",
  "Form1099Records": {
    "SuccessRecords": [
      {
        "SequenceId": "1",
        "RecordId": "63f0aaf2-7b35-487d-a003-0be8b522ef47",
        "RecipientId": "775acc48-7492-487b-8edc-6c4d9877136f",
        "AccountNum": "20123130000009000001",
        "FederalReturn": {
          "Status": "CREATED",
          "StatusTs": "2021-08-23 01:45:52 -04:00",
          "Info": null
        },
        "StateReturns": [
          {
            "StateCd": "WV",
            "Status": "CREATED",
            "StatusTs": "2021-08-23 01:45:54 -04:00",
            "Info": null,
            "Errors": null
          },
          {
            "StateCd": "ID",
            "Status": "CREATED",
            "StatusTs": "2021-08-23 01:45:54 -04:00",
            "Info": null,
            "Errors": null
          }
        ],
        "Postal": {
          "Status": "CREATED",
          "StatusTs": "2021-08-23 01:45:54 -04:00",
          "Info": null
        },
        "OnlineAccess": {
          "Status": "CREATED",
          "Email": "john@gmail.com",
          "Info": null
        },
        "ScheduleFiling": {
          "ScheduledOn": null,
          "Info": "This Service will be available soon"
        }
      }
    ],
    "ErrorRecords": null
  },
  "Errors": null
}

1
2
3
4
5
6
7
8
9
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
51
52
53
54
55
56

# Delete

Deletes Form 1099-NEC return created in TaxBandits. Transmitted forms cannot be deleted.

DELETE Form1099NEC/Delete

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
RecordIds	guid[]	An unique identifier generated by TaxBandits when a 1099-NEC return is created. Mention the 1099-NEC return's Record ID that you want to delete.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
Form1099Records	object	Pulls the Form 1099 NEC records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form 1099 NEC Records
SequenceId	string	A unique number given by an inbound application to identify failed records
RecordId	Guid	Unique identifier of a record
Status	string	Returns the status of the records.
StatusTs	string	Date and time of return deleted.
ErrorRecords	object[]	It will show the detailed information about the error status of Form 1099 NEC Records.
SequenceId	string	A unique number given by an inbound application to identify failed records
RecordId	Guid	Unique identifier of a record
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error code
Name	string	Name of the validation error
Message	string	Description of the validation error
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error code
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

Form1099NEC/Delete?SubmissionId=9d71ae45-df5f-49f7-86f8-e88f54132fa1&RecordIds=01132f6d-ef4a-4014-817e-94a5a19bd52b,eb39714e-f653-4c4d-a53c-07f24f9a9dj5

Response JSON

{
   "StatusCode": 200,
   "StatusName": "Ok",
   "StatusMessage": "Successful API call",
"SubmissionId": "9d71ae45-df5f-49f7-86f8-e88f54132fa1",
   "Form1099Records": {
       "SuccessRecords": [
           {
               "SequenceId": "1",
               "RecordId": "15c3caa6-8402-4548-8713-4fcdd2f7d42d",
               "Status": "DELETED",
               "StatusTs": "2021-08-05 06:26:16 -04:00"
           },
           {
               "SequenceId": "2",
               "RecordId": "eb39714e-f653-4c4d-a53c-07f24f9a9dj5",
               "Status": "DELETED",
               "StatusTs": "2021-08-05 06:26:16 -04:00"
           }
       ],
       "ErrorRecords": null
   },
   "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# GenerateFromTxns

If you are using TaxBandits API to send Transactions and then generate 1099s using the transactions data, then this endpoint will be applicable to you. This endpoint will generate Form 1099-NECs for the given BusinessID and RecipientIDs based on the transactions reported. In response, a SubmissionID/RecordIds will be generated, which can be further used as a reference for all other methods of the 1099-NEC API.

POST Form1099NEC/GenerateFromTxns

Request Body

Field	Type	Description
TaxYear	string	Tax year of Form 1099-NEC to be filed. Allowed values: "2021"
Business	object[]	Payer Information. Either PayerRef, BusinessId or TIN is mandatory.
PayerRef	string	Unique identifier of the payer. Set by the client.
BusinessId	Guid	Unique identifier of the payer. Generated by TaxBandits.
TINType	string	TIN Type of the business. Allowed values: "SSN", "EIN"
TIN	string	TIN Type of the business. Size Range: 9-11
Recipients	object[]	Recipient Information.
PayeeRef	string	Unique identifier of the recipient. Set by the client. Size Range: 4..20
RecipientId	Guid	Unique identifier of the recipient. Generated by TaxBandits.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
BusinessId	Guid	TaxBandits Unique Business Identifier.
PayerRef	string	Unique identifier of the payer. Set by the client in the endpoint Business/RequestByUrl.
Form1099NECRecords	object	Lists the 1099-NECs generated
SuccessRecords	object[]	It will show the detailed information about the 1099-NEC forms generated.
PayeeRef	string	Unique identifier of the recipient. Set by the client.
NoOf1099	number	Shows the number of 1099NECs generated.
RecipientId	Guid	An unique identifier of the recipient. Generated by TaxBandits
RecordId	Guid	An unique identifier of the 1099-NEC form generated by TaxBandits. Use this as a future reference to Approve, Update, Delete and Transmit.
FederalReturn	object	Federal return information
Status	string	Federal return status.
StatusTs	string	Status timestamp.
Info	string	Additional information of the Federal return (If any)
ErrorRecords	object[]	Contains the list of errors
PayeeRef	string	Unique identifier of the recipient. Set by the client.
RecipientId	Guid	Unique identifier of the recipient. Generated by TaxBandits.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description ofthe validation error
Errors	object[]	Shows the detailed error information
Id	string	Validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
 "TaxYear": "2021",
 "Business": {
   "PayerRef": "1473",
   "BusinessId": null,
   "TINType": null,
   "TIN": null
 },
 "Recipients": [
   {
     "PayeeRef": "2a-ed6789896",
     "RecipientId": "87626E20-75B2-4CB5-A2AC-B65C0105FA5C"
   },
   {
     "PayeeRef": "Alex9608912",
     "RecipientId": "A6316079-C3F9-4AAD-BA99-6DF71F635AD3"
   }
 ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Response JSON

{
 "SubmissionId": "8f5c57ec-5c9e-4dee-a650-e79eeb087e4c",
 "BusinessId": "1cc352d4-6d91-4fd5-a886-7b59b9fbe2e8",
 "PayerRef": "1473",
 "NoOf1099": "2",
 "Form1099NECRecords": {
   "SuccessRecords": [
     {
       "PayeeRef": "2a-ed6789896",
       "RecordId": "5ef596cc-70e2-4258-885c-e5e18d48fa70",
       "RecipientId": "87626E20-75B2-4CB5-A2AC-B65C0105FA5C",
       "NECBox1": "10000",
       "NECBox4": "2000",
       "FederalReturn": {
         "Status": "CREATED",
         "StatusTs": "2021-10-14 10:58:19 +05:30",
         "Info": null
       }
     },
     {
       "PayeeRef": "Alex9608912",
       "RecordId": "5ef596cc-70e2-4258-885c-e5e18d48ff78",
       "RecipientId": "A6316079-C3F9-4AAD-BA99-6DF71F635AD3",
       "NECBox1": "10000",
       "NECBox4": "2000",
       "FederalReturn": {
         "Status": "CREATED",
         "StatusTs": "2021-10-14 10:58:19 +05:30",
         "Info": null
       }
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}

1
2
3
4
5
6
7
8
9
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

# Get

Retrieves the Form 1099-NEC return information based on the Submission Id and RecordIds given in the request.

GET Form1099NEC/Get

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
RecordIds	Guid[]	An unique identifier generated by TaxBandits when a 1099-NEC return is created. Mention the Form 1099-NEC return's Record ID that you want to Get.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
Form1099Records	object	Contains information about Form 1099 NEC returns.
SubmissionManifest	object	SubmissionManifest provides the brief information about a particular submission on the whole. It contains information like Submission ID, Tax Year, IsPostal, IsFederalFiling, IsStateFiling, IsOnlineAccess, IsScheduleFiling & ScheduleFiling service details.
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
TaxYear	string	Tax year of Form 1099 NEC to be filed. Allowed values: "2021"
IsFederalFiling	Boolean	Federal Filing for the return will be enabled when the value is True. The Form 1099-NEC will be sent directly to the IRS.
IsStateFiling	Boolean	State Filing for the return will be enabled when the value is True. Form 1099-NEC forms will be directly filed with the respective recipient states. Note: State Filing will not be created for the states that do not require State filing.
IsPostal	Boolean	Postal Order will be created when the value is set as True. Once the return is Transmitted, Form 1099-NEC Recipient copies will be postal mailed to the recipient's address via USPS. Note: Postal Orders for Foreign Address will not be created.
IsOnlineAccess	Boolean	Online Access will be enabled when the value is set as True. Once the return is Transmitted, an email with the link to the secure TaxBandits portal will be sent to the Recipient. The recipient can provide consent and download Form 1099-NEC Recipient copies from the portal.
IsScheduleFiling	Boolean	When true, schedule filing services will be provided for Form 1099 NEC returns under this submission.
ScheduleFiling	object	Contains preferred date to submit the returns to the IRS. Required only when "IsScheduleFiling" is True.
EfileDate	string	Date of Schedule Filing. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY Example: 10/20/2021 or 10-20-2021
ReturnHeader	object	Contains information about the Business details.
Business	object	Object to identify the Business Details.
BusinessId	Guid	Returns the unique Business ID for the Business. It can be used in future to refer the same business.
PayerRef	string	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: ..50
BusinessNm	string	Name of the business Size Range: ..75
TradeNm	string	`Optional` Name under which the business operates Size Range: ..75
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	string	Returns the Employer Identification Number of Business Size Range: 9
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	`Optional` Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Phone number of the business Size Range: 10
PhoneExtn	string	`Optional` Extension of the business phone number Size Range: ..5
Fax	string	`Optional` Fax number of the Business Size Range: 10
BusinessType	string	`Optional` Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: ..4 Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
SigningAuthority	object	`Optional` Details of the person who is authorized to sign the return
Name	string	`Optional` Name of the signing authority Size Range: ..35
Phone	string	`Optional` Phone number of the signing authority Size Range: 10
BusinessMemberType	string	`Optional` Business title of the signing authority 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	`Optional` Identifies the kind of employer. Mandatory for W-2 and optional for Form 1099-NEC and 94X series Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	`Optional` Identifies the kind of payer. This field is mandatory in W-2 and optional in Form 1099-NEC and 94X series Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
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	Employer/Payer's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	Employer/Payer'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	Employer/Payer's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the business
Address1	string	Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer's country Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
ReturnData	object[]	Contains information about the recipient details and Form 1099 NEC details.
RecordId	Guid	Unique identifier of a record. Not required when you are creating a return.
SequenceId	string	An 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.
Recipient	object	Object to identify the recipient details.
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient when a 1099-NEC return is created. You can use this id for your future reference to Update.
TINType	string	Specify the TIN type of the recipient. Allowed values: "SSN", "EIN", "ITIN", "ATIN", "N/A"
TIN	string	Enter the nine-digit taxpayer identification number of the Recipient (SSN, ITIN, ATIN, or EIN). Size Range: 9
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.
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.
IsForeign	Boolean	When true, identifies the recipient address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the recipient
Address1	string	Recipient's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city Size Range: ..27
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
ForeignAddress	object	If IsForeign is true, pass foreign address of the recipient
Address1	string	Recipient's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city. Size Range: ..27
ProvinceOrStateNm	string	Recipient's Province or State Name. Size Range: ..30
Country	string	Recipient's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Recipient's Postal Code
Email	string	Recipient's email address. Size Range: 0..40
Fax	string	`Optional` Recipient's Fax number. Size Range: 10
Phone	string	Recipient's Phone Number. Size Range: 10
NECFormData	object	Recipient's Form 1099 NEC information.
B1NEC	number	Gets the Nonemployee compensation (NEC) amount of $600 or more. Size Range: 0-9999999999.99
B2IsDirectSales	Boolean	When true, identifies sales of $5,000 or more of consumer products to a person on a buy-sell, deposit commission, or any other commission basis for resale anywhere other than in a permanent retail establishment. Applicable only for Tax year 2021.
B4FedTaxWH	number	Gets the amount of Federal Tax Withheld. Size Range: 0-9999999999.99
IsFATCA	Boolean	When true, identifies a U.S. payer reporting on Form(s) 1099 (including reporting payments on this Form 1099-NEC) to satisfy their foreign financial asset reporting requirement with respect to a U.S. account. Not Applicable for Tax year 2021.
AccountNum	string	Account number of Payer having multiple accounts for a recipient for whom more than one Form 1099-NEC is filed. Size Range: 4..20
Is2ndTINnot	Boolean	When true, identifies a Payer who is notified by the IRS twice within 3 calendar years for providing an incorrect TIN and do not want the IRS to send any more notices.
States	object[]	Contains list of state returns information.
StateCd	string	State Code. 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"
StateIdNum	string	Identification Number of State. Size Range: ..20
StateWH	number	Income tax amount withheld for State . Size Range: 0-9999999999.99
StateReconData	object	Collects State Recon fields specific for each state. Click here, for the description of each state specific Recon fields.
StateIncome	number	Amount of payment for State. Size Range: 0-9999999999.99
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

Request JSON

Form1099NEC/Get?SubmissionId=e88e7f1d-7ae5-43b6-99f6-38d85664035a&RecordIds=63f0aaf2-7b35-487d-a003-0be8b522ef47

Response JSON

{
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "Form1099Records": {
   "SubmissionManifest": {
     "SubmissionId": "e88e7f1d-7ae5-43b6-99f6-38d85664035a",
     "TaxYear": "2021",
     "IsFederalFiling": true,
     "IsStateFiling": true,
     "IsPostal": true,
     "IsOnlineAccess": true,
     "IsScheduleFiling": true,
     "ScheduleFiling": {
       "EfileDate": "12/12/2021"
     }
   },
   "ReturnHeader": {
     "Business": {
       "BusinessId": "c21df64f-9a6d-4e21-ac67-723aacf1ba48",
       "PayerRef": "Pe123",
       "BusinessNm": "Eastman Kodak Com",
       "TradeNm": "Kodak",
       "IsEIN": true,
       "EINorSSN": "62-7369245",
       "Email": "john@gmail.com",
       "ContactNm": "John",
       "Phone": "(123) 456-7890",
       "PhoneExtn": "12345",
       "Fax": "(123) 456-7890",
       "BusinessType": "ESTE",
       "SigningAuthority": {
         "Name": "John",
         "Phone": "(123) 456-7890",
         "BusinessMemberType": "ADMINISTRATOR"
       },
       "KindOfEmployer": "FEDERALGOVT",
       "KindOfPayer": "REGULAR941",
       "IsBusinessTerminated": true,
       "IsForeign": false,
       "USAddress": {
         "Address1": "1751 Kinsey Rd",
         "Address2": "Main St",
         "City": "Dothan",
         "State": "AL",
         "ZipCd": "36303"
       },
       "ForeignAddress": null
     }
   },
   "ReturnData": [
     {
       "RecordId": "63f0aaf2-7b35-487d-a003-0be8b522ef47",
       "SequenceId": "1",
       "Recipient": {
         "RecipientId": "775acc48-7492-487b-8edc-6c4d9877136f",
         "TINType": "EIN",
         "TIN": "39-3817572",
         "FirstPayeeNm": "Mark",
         "SecondPayeeNm": "Davis",
         "IsForeign": false,
         "USAddress": {
           "Address1": "1751 Kinsey Rd",
           "Address2": "Main St",
           "City": "Dothan",
           "State": "AL",
           "ZipCd": "36303"
         },
         "ForeignAddress": null,
         "Email": "john@gmail.com",
         "Fax": "(123) 456-7890",
         "Phone": "(123) 456-7890"
       },
       "NECFormData": {
         "B1NEC": 100,
         "B2IsDirectSales": true,  
         "B4FedTaxWH": 40.55,
         "IsFATCA": false,
         "AccountNum": "20123130000009000001",
         "Is2ndTINnot": true,
         "States": [
           {
             "StateCd": "WV",
             "StateWH": 257.94,
             "StateIdNum": "99999999",
             "StateIncome": 2900
           },
           {
             "StateCd": "ID",
             "StateWH": 15,
             "StateIdNum": "999999999",
             "StateIncome": 16
           }
         ]
       }
     }
   ],
   "StateReconData": {
     "ID": {
       "Form967": {
         "IDWithHoldingID": "999999999",
         "TotWagesW2": 0,
         "TotTaxWHW2": 200,
         "NumOfW2Forms": 0,
         "TotTaxWH1099": 400,
         "NumOf1099Forms": 40,
         "TotNumOf1099W2": 40,
         "NumOf1099WithWH": 30,
         "TotTaxWH": 600,
         "WHTaxPaid": 500,
         "BalanceDue": 100,
         "Overpayment": 0,
         "PenaltyOnBalanceDue": 100,
         "InterestOnBalanceDue": 100,
         "BalanceDuePenaltyInt": 300,
         "LateFilingPenalty": 200,
         "TotBalanceDue": 500,
         "TotOverPayment": 0,
         "Is1099CFSF": true,
         "FilingCycle": "ANNUAL"
       }
     },
     "PA": null,
     "WV": {
       "FormIT103": {
         "WVWithHoldingID": "99999998",
         "NumOf1099W2": 24,
         "TotalTaxWH1099W2": 404,
         "WHTaxDue": {
           "WVTaxQ1": 101,
           "WVTaxQ2": 101,
           "WVTaxQ3": 101,
           "WVTaxQ4": 101,
           "TotalForYear": 404
         }
       }
     }
   }
 },
 "Errors": null
}

# GetPDF

Retrieves Form 1099 NEC PDFs. The link for PDFs download will be sent via Webhook after successful API call.

GET Form1099NEC/GetPDF

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
RecordIds	Guid[]	`Optional` Unique identifier of a records.
TINMaskType	string	`Optional` Choose the masking type of your Recipient's TIN on the 1099-NEC PDF. MASKED - The Recipient's TIN will be masked in the PDF. Only last 4 digits of the TIN can be read. UNMASKED - The Recipient's TIN will not be masked in the PDF. To protect the PII information of the Recipient, the PDF with Unmasked TIN is password protected. Use the Recipient's TIN (password) to open the protected file. BOTH - Two PDF's will be delivered for each Recipient. One with Masked TIN and the other with Unmasked TIN. The PDF with Unmasked TIN will be password protected. Allowed values: "MASKED", "UNMASKED", "BOTH"

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
Form1099NecRecords	object[]	Collection of Form 1099-NEC records for which the PDF will be successfully delivered
RecordId	guid	Unique identifier of a record
Message	string	Provides additional information regarding the PDF delivery.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error code
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

Form1099NEC/GetPdf?SubmissionId=9d71ae45-df5f-49f7-86f8-e88f54132fa1&RecordIds=01132f6d-ef4a-4014-817e-94a5a19bd52b,eb39714e-f653-4c4d-a53c-07f24f9a9dj5&TINMaskType=UNMASKED

Response JSON

{
   "StatusCode": 200,
   "StatusName": "Ok",
   "StatusMessage": "Successful API call",
   "SubmissionId": "9d71ae45-df5f-49f7-86f8-e88f54132fa1",
   "Form1099NecRecords": [
       {
           "RecordId": "01132f6d-ef4a-4014-817e-94a5a19bd52b",
           "Message": "We've successfully received your request to generate PDF. You will be notified with the URL to download the PDF."
       },
       {
           "RecordId": "eb39714e-f653-4c4d-a53c-07f24f9a9dj5",
           "Message": "We've successfully received your request to generate PDF. You will be notified with the URL to download the PDF."
       }
   ],
   "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# List

Lists all Form 1099-NEC returns created and transmitted on the account for a particular Submission or Payer. Form 1099-NEC returns will be listed based on the filters sent in the Request.

GET Form1099NEC/List

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a business
TINType	string	List the 1099 NEC records based on the given TINType and TIN.
TIN	string	List the 1099 NEC records based on the given TIN.
TaxYear	string	List the 1099 NEC records based on the given taxyear.
Page	number	Pulls the records listed in the page selected
PageSize	number	Number of 1099 NEC records to be listed in each page.
EfileStatus	string	List the 1099 NEC records based on the status ("CREATED, UNDERPROCESS, SENTTOAGENCY, TRANSMITTED, ACCEPTED, REJECTED")
FromDate	string	List 1099 NEC records created from
ToDate	string	List 1099 NEC records created up to

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
Form1099Type	string	Denotes the type of 1099 form.
Form1099Records	object[]	Returns detailed information of the Form 1099 NEC records.
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a business
PayerRef	string	Unique identifier of the payer.
BusinessNm	string	Name of the business
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	string	Employer Identification Number or Social Security Number.
ContactNm	string	Contact Name of the Business.
TaxYr	string	Tax year of 1099 NEC to be filed.
Recipient	object	Details of the Recipient.
SequenceId	string	An 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.
RecordId	Guid	An unique identifier generated by TaxBandits when a 1099-NEC return is created.
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient when a 1099-NEC return is created. You can use this id for your future reference to Update.
RecipientNm	Boolean	Name of Recipient.
TINType	string	TIN type of the Recipient.
TIN	string	TIN of the Recipient.
Status	string	The status of Form 1099 NEC.
TotalRecords	number	Total number of records.
TotalPages	number	Total number of pages.
Page	number	Pulls the records listed in the page selected
PageSize	number	Number of 1099 NEC records to be listed in each page.
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

Request JSON

"Form1099NEC/List?SubmissionId=1a333c54-1d01-41bf-8283-f43211e918c4&BusinessId=8d6e3938-2af4-41d2-ba02-17796f00aae2&TINType=SSN&TIN=092115111&TaxYear=2021&Page=1&PageSize=10&EfileStatus=ALL&FromDate=11-01-2021&ToDate=11-30-2021"

Response JSON

{
   "StatusCode": 200,
   "StatusName": "Ok",
   "StatusMessage": "Successful API call",
   "Form1099Type": "NEC",
   "Form1099Records": [
       {
           "SubmissionId": "1a333c54-1d01-41bf-8283-f43211e918c4",
           "BusinessId": "8d6e3938-2af4-41d2-ba02-17796f00aae2",
           "PayerRef": "Pe123",
           "BusinessNm": "Brian LLC",
           "IsEIN": false,
           "EINorSSN": "092-11-5111",
           "ContactNm": "Brian O Relly",
           "TaxYear": "2021",
           "Recipient": {
               "SequenceId": "001",
               "RecordId": "1ee98e82-b1f0-43f7-9e0c-95b3a1e90ff9",
               "RecipientId": "91676dd6-ddba-41a4-8a9f-3bff130df96b",
               "RecipientNm": "Mark Davis",
               "TINType": "ATIN",
               "TIN": "391-11-4511",
               "Status": "CREATED"
           }
       }
   ],
   "TotalRecords": 1,
   "TotalPages": 1,
   "Page": 1,
   "PageSize": 10,
   "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# RequestDistUrl

You can request an URL via the TaxBandits API endpoint. TaxBandits will generate a unique URL from which the recipients can view and download 1099. (The logo and redirection URLs can be customized).

This endpoint is for the Hosted API URL method to electronically distribute the forms to the recipients.

Note: The RequestDistUrl endpoint can be called only when the 1099-NEC form is Transmitted for the recipient.

How does it work?

The first step is to call the Auth method to get the access token. You supply this access token in the request header as the ‘Bearer‘ token.

Refer OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.

The second step is to call the [POST] Form1099NEC/RequestDistURL endpoint. If you are trying to embed this link into your web page, you must call this endpoint before loading the page. Parameters to be passed are:
- Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API)
- Recipient Id - Unique Identifier of the recipient - This identifies the recipient to whom the 1099 needs to be shown. You will receive the RecipientID in the Webhook response of Form W-9 completion and in the Response of Form 1099 Create endpoint.
- Business Logo and Callback URLs (Optional) - You can add the business logo on the 1099 retrieval page and also set the callback redirection for the recipient to return to a specific page in your portal after downloading the 1099 form.
TaxBandits will generate a unique URL and send the link in the response. You must embed this link into the page or show it by itself (Hosted Solution) for your recipients.

When the recipient clicks the link, they will be redirected to a page that will show a consent form. This recipient has to agree to receive the 1099 form electronically. Only then they will be able to download the 1099 form.

You can customize the page with your logo and theme. In addition, you can provide a redirection URL in the request. A button will be shown on the page, which will redirect them to your portal.

POST Form1099NEC/RequestDistUrl

Request Body

Field	Type	Description
TaxYear	string	Tax year of Form 1099 NEC to be filed. Allowed values: "2021"
RecordId	Guid	Unique identifier of a record.
Business	object	Payer Information.
BusinessId	Guid	Unique identifier of the payer. Generated by TaxBandits.
PayerRef	string	Unique identifier of the payer. Set by the client.
TINType	string	TIN Type of the business. Allowed values: "SSN,EIN"
TIN	string	Taxpayer Identification Number of the business. Size Range: 9-11
Recipient	object	Recipient Information.
PayeeRef	string	Unique identifier of the recipient. Set by the client.
RecipientId	Guid	Unique identifier of the recipient. Generated by TaxBandits.
TINType	string	Specify the TIN type of the recipient. Allowed values: "SSN,EIN"
TIN	string	Enter the nine-digit taxpayer identification number of the Recipient (SSN, ITIN, ATIN, or EIN).
Customization	object	Business Portal Information.
BusinessLogoUrl	string	`Optional` Business Logo that will be displayed on the 1099 Retrieval page Size Range: 1..50
ReturnUrl	string	`Optional` Return Redirection URL. Set the callback URL to direct the recipient from the 1099 page back to your portal. Size Range: 1..50
CancelUrl	string	Canceling the Return Redirection URL.
ExpiryTime	number	Number of times the link is accessible.

Response Body

Field	Type	Description
RecipientId	Guid	Unique identifier of the recipient.
DistributionUrl	string	URL that can be embedded on your portal using Iframe or other means.
Errors	object[]	Collection of errors for the Recipient.
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
   "TaxYear": "2021",
   "RecordId": "187e06a0-6754-4e7f-84e8-7ba79a408a19",
   "Business": {
       "BusinessId": "44cdcbaf-3612-40a5-b155-f9544b7a8365",
       "TINType": "EIN",
       "TIN": "404288154"
   },
   "Recipient": {
       "RecipientId": "36b96057-3a9d-4c4f-a9d1-f8b83cf4acc4",
       "TINType": "SSN",
       "TIN": "362123522"
   },
   "Customization": {
       "BusinessLogoUrl": "https://refersion.efile4taxes.com/Content/Images/refersion.png",
       "ReturnUrl": "https://www.google.com/",
       "CancelUrl": "https://example.com",
       "ExpiryTime": "5"
   }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Response JSON

{
   "RecipientId": "36b96057-3a9d-4c4f-a9d1-f8b83cf4acc4",
   "DistributionUrl": "https://onlineaccess.tbsuat.com?uid=11d22666-3ea0-4f78-8bc1-ba427feea1bd",
   "Errors": null
}

1
2
3
4
5

# RequestDraftPdfUrl

This API request will return the Draft PDF of the forms that are not transmitted yet for review purpose. The draft PDF will have copy A of the form with For Review Only watermark text.

Note: You can only retrieve PDF of a single record/form using this method.

How does it works?

Call the [POST] Form1099NEC/RequestDraftPdfUrl endpoint. You will need to supply the following parameters:
- Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API)
- Request Parameters: Specify the RecordId for the form you need the Draft PDF form. If you do not have the RecordId, then you request the PDF using the following parameters
  - Business Reference - Use the business reference PayerRef or BusinessId or TIN.
  - Recipient Reference - Use the recipient reference PayeeRef or RecipientId or TIN.
  - Tax Year - Tax year of the form you are requesting the PDF.

POST Form1099NEC/RequestDraftPdfUrl

Request Body

Field	Type	Description
RecordId	Guid	`Optional` Specify the RecordId of the return
TINMaskType	string	`Optional` TIN Mask type on the TIN printed on the PDF Allowed values: "MASKED", "UNMASKED"
TaxYear	string	`Optional` Tax Year of the return. Specify only if you do not have the RecordId
Business	object	`Optional` Collects the Business identifier TIN or TBS Business Id or PayerRef. This object information is required only if you do not have the RecordId
BusinessId	Guid	`Optional` TaxBandits Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
PayerRef	string	`Optional` Unique payer identifier assigned by the client. Size Range: 1 to 50
TINType	string	`Optional` TIN type of the Business TIN. Use this as an alternative for BusinessId or PayerRef. Allowed values: "SSN,EIN"
TIN	string	`Optional` Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef. Size Range: 9 to 11
Recipient	object	`Optional` Collects the recipient's unique identifier. This object information is required only if you do not have the RecordId
PayeeRef	string	`Optional` An unique identifier for each recipient set by the client. Size Range: 1 to 50
RecipientId	Guid	`Optional` Unique Recipient Identifier generated by TaxBandits
TINType	string	`Optional` TIN type of the Recipient's TIN. Use this as an alternative for RecipientId or PayeeRef. Allowed values: "SSN,EIN"
TIN	string	`Optional` Taxpayer Identification Number. Use this as an alternative for RecipientId or PayeeRef.

Response Body

Field	Type	Description
RecordId	Guid	Unique identifier of the record
RecipientId	Guid	Unique Recipient Identifier generated by TaxBandits
PayeeRef	string	An unique identifier for each recipient set by the client.
DraftPdfUrl	string	URL of the Draft PDF
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error code
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON 1: With just the RecordId

{
  "TaxYear": null,
  "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
  "Business": null,
  "Recipient": null
}

1
2
3
4
5
6

Response JSON 1

{
  "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
  "RecipientId": "bd2221f7-4be6-4cc7-813c-6346e23b9f63",
  "PayeeRef": null,
  "DraftPdfUrl":"https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148/3e99f728-e9d4-4d88-99b6-e00638da7a5b/1099/221556/d/copy_tbs_wm_1up_221556.pdf",
  "Error": null
}

1
2
3
4
5
6
7

Request JSON 2: With No RecordId

{
 "TaxYear": "2021",
 "RecordId": null,
 "Business": {
   "BusinessId": "94B6214D-8DCA-490C-8FC3-602840B439B5",
   "PayerRef": null,
   "TINType": null,
   "TIN": null
 },
 "Recipient": {
   "RecipientId": "6DDFFB5A-565F-402D-8602-7ECD917CEC04",
   "PayeeRef": null,
   "TINType": null,
   "TIN": null
 }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Response JSON 2

{
  "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
  "RecipientId": "6DDFFB5A-565F-402D-8602-7ECD917CEC04",
  "PayeeRef": null,
  "DraftPdfUrl":"https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148/3e99f728-e9d4-4d88-99b6-e00638da7a5b/1099/221556/d/copy_tbs_wm_1up_221556.pdf",
  "Error": null
}

1
2
3
4
5
6
7

# RequestPdfURLs

This method can be used to retrieve PDFs for single or multiple recipients. The PDF URL will be returned in the response only if it is already generated by us. You can use the SubmissionId or RecordIds to request the pdf URLs.

Note: The PDF URL will be returned in response only after the return is transmitted in the API. This method will not work for Inprogress returns.

POST Form1099NEC/RequestPdfURLs

Request Body

Field	Type	Description
SubmissionId	Guid	`Optional` Unique identifier of an API submission. Use this node to request the PDFs under a particular submission. If you are going to request the PDFs using the RecordIds, then leave the SubmissionId blank or null.
RecordIds	object[]	Contains the list of RecordIds for which you are requesting the pdf URLs
RecordId	Guid	Unique identifier of the return.
Customization	object	Contains PDF customizations
TINMaskType	string	`Optional` Mention whether you want the TIN to be masked in the PDF. If masked, only the last digits of the SSN will be visible and the rest of the digits will be crossed (xxx-xx-1234). Allowed values: "MASKED", "UNMASKED", "BOTH"

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
Form1099NecRecords	object	Contains success and error records of the requested RecordIds.
SuccessRecords	object[]	Contains the successful records with pdf urls if the forms are generated.
RecordId	Guid	Unique identifier of the return.
Status	string	Status of the PDF in TaxBandits. Success - The PDF is generated and you can download it.
Files	object	Contains multiple copies of a particular return.
Copy1	object	Copy 1: For State Tax Department
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
Copy2	object	Copy 2: To be filed with recipients state income tax return, when required.
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
CopyB	object	Copy B: For Recipient
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
CopyC	object	Copy C: For Payer
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
ErrorRecords	object[]	Contains the error records
RecordId	Guid	Unique identifier of the return.
Status	string	Status of the error record. PDF_Not_Generated - PDF is yet to be generated. You will have to wait and send a new API request to get the PDF. Not Transmitted - The return is not transmitted yet. Invalid RecordId - Given record id is invalid
Message	string	Description of each statuses
Errors	object[]	Lists the errors in the API call
Id	string	Returns the error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.

Sample Request JSON 1

{
  "SubmissionId": "d5111958-4e93-4121-a861-cee4d18687b3",
  "RecordIds": [
    {
      "RecordId": "5a24c4c5-3b32-4327-9ffa-88b390f9dfe8"
    }
  ],
  "Customization": {
    "TINMaskType": "Masked"
  }
}

1
2
3
4
5
6
7
8
9
10
11

Sample Response JSON 1

{
   "SubmissionId": "d5111958-4e93-4121-a861-cee4d18687b3",
   "Form1099NecRecords": {
       "SuccessRecords": [
           {
               "RecordId": "5a24c4c5-3b32-4327-9ffa-88b390f9dfe8",
               "Status": "Success",
               "Files": {
                   "Copy1": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64a50f-444ab16f50d0/17ce46feab02-4224-bed4-ed57caba02fd/1099/0eed705e-1546-4fc1-88db-778fe2425686/m/copy1_1up_9943341397.pdf"
                   },
                   "Copy2": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64a50f-444ab16f50d0/17ce46feab02-4224-bed4-ed57caba02fd/1099/0eed705e-1546-4fc1-88db-778fe2425686/m/copy2_1up_6258427971.pdf"
                   },
                   "CopyB": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64a50f-444ab16f50d0/17ce46feab02-4224-bed4-ed57caba02fd/1099/0eed705e-1546-4fc1-88db-778fe2425686/m/copyb_1up_4385946292.pdf"
                   },
                   "CopyC": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64a50f-444ab16f50d0/17ce46feab02-4224-bed4-ed57caba02fd/1099/0eed705e-1546-4fc1-88db-778fe2425686/m/copyc_1up_3803212351.pdf"
                   }
               }
           }
       ],
       "ErrorRecords": null
   },
   "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Sample Request JSON 2

{
 "SubmissionId": "a863c015-91f1-4128-84fc-bb38922b80f9",
 "RecordIds": [
   {
     "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267"
   },
   {
     "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e"
   }
 ],
 "Customization": {
   "TINMaskType": "Masked"
 }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Sample Response JSON 2

{
   "SubmissionId": null,
   "Form1099NecRecords": {
       "SuccessRecords": null,
       "ErrorRecords": [
           {
               "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267",
               "Status": "PDF_Not_Generated",
               "Message": "Your PDF request is prioritized in the queue.Please try again after sometime"
           },
           {
               "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e",
               "Status": "Not Transmitted",
               "Message": "Given RecordId is not transmitted"
           }
       ]
   },
   "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Sample Request JSON 3

{
   "RecordIds": [
   {
     "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267"
   },
   {
     "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e"
   }
 ]

}

1
2
3
4
5
6
7
8
9
10
11

Sample Response JSON 3

{
   "SubmissionId": null,
   "Form1099NecRecords": {
       "SuccessRecords": null,
       "ErrorRecords": [
           {
               "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267",
               "Status": "PDF_Not_Generated",
               "Message": "Your PDF request is prioritized in the queue.Please try again after sometime"
           },
           {
               "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e",
               "Status": "Not Transmitted",
               "Message": "Given RecordId is not transmitted"
           }
       ]
   },
   "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Status

This method will return the current status of Form 1099 for a particular submission or for a particular employee.

Federal Return Statuses:

Created: Form 1099 has been created and not yet transmitted by the user.
Transmitted: Form 1099 has been transmitted by the user.
Order Received: Form 1099 order is received and waiting in our efile queue.
Under Process: Our efile system is processing the Form 1099 which will be sent to the IRS soon.
Sent to Agency: Form 1099 has been sent to the SSA and we are waiting for the result from IRS.
Accepted: Form 1099 is accepted by the IRS.
Rejected: Form 1099 is rejected by the IRS due to some errors. Please correct the errors and retransmit them.

State Return Statuses:

Not Created: State filing is not opted for the return. IsStateFiling in the submission manifest must be set as TRUE to enable state filing.
Created: Form 1099 state return has been created and not yet transmitted by the user.
Transmitted: Form 1099 state return has been transmitted by the user.
Order Received: State order is received and waiting in our efile queue.
Under Process: Our efile system is processing the Form 1099 for the state which will be sent to the state DOR soon.
Sent to Agency: Form 1099 State return has been sent to the DOR and we are waiting for the result.
Accepted: Form 1099 state return is accepted by the DOR.
Rejected: Form 1099 state return is rejected by the DOR due to some errors. Please correct the errors and retransmit them.

Postal Mailing Statuses:

Not Created: Postal Mailing is not opted for the return. IsPostalMailing in the submission manifest must be set as TRUE to enable postal mailing. Postal Mailing cannot be created for recipients with Foreign addresses.
Created: Postal Mailing service is opted for the return and it will be sent as soon as the form is transmitted.
Order Received: Postal Mailing order has been received and the mails will be sent out soon.
Order Sent: Postal Mailing order has been sent and the recipient will receive the copy soon.

Online Access Statuses:

Not Created: Online Access service is not opted for the return. IsOnlineAccess in the submission manifest must be set as TRUE to enable Online Access.Email Address is required to create Online Access.
Created: Online Access service is opted for the return and the email with a secure link to download their forms will be sent to the recipients as soon as the form is transmitted.
Order Received: Online Access order has been received and the email will be sent to the recipient soon.
Email Sent: Online Access email with a secure link to download the form has been sent to the recipient and the recipient is yet to view the form.
Viewed Form: Recipient has successfully viewed the form.
Downloaded Form: Recipient has successfully viewed and downloaded the form.

GET Form1099NEC/Status

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
RecordIds	Guid[]	List of record Ids to get the status of Form 1099 NEC.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a Business.
PayerRef	string	Unique identifier of the payer.
Form1099Type	string	Denotes the type of 1099 form.
Form1099Records	object	Pulls Form 1099 NEC records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form 1099 NEC Records
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient when a 1099-NEC return is created. You can use this id for your future reference to Update.
FederalReturn	object	Returns the record status and StatusTs of federal return.
Status	string	Returns the record status.
StatusTs	string	Returns date and time of return created.
Info	string	Returns information about the Federal Filing service.
StateReturns	object[]	Returns collection of state
StateCd	string	Returns the state code of the state which the return filed.
Status	string	Returns the record status of the state return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the state for which we are not state filing.
Errors	object[]	Shows error information of state returns of Form 1099 NEC
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
Postal	object	Returns the status and StatusTs of postal mailing service for Form 1099 NEC.
Status	string	Returns the status of postal order.
StatusTs	string	Returns the date and time of the postal order created.
Info	string	Returns the information about Postal mailing service.
OnlineAccess	object	Returns the Email address for whom the online access to be given and Status of online access.
Status	string	Returns status of online access for Form 1099 NEC return.
Email	string	Email address for whom the online access to be given.
Info	string	Information about the online access service.
ScheduleFiling	object	Returns the date of the schedule filing.
ScheduledOn	string	Date of the schedule filing to know when the return to be filed to the IRS.
Info	string	Information about Schedule Filing service.
ErrorRecords	object[]	It will show the detailed information about the error status of Form 1099 NEC Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
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
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

Request JSON

Form1099NEC/Status?SubmissionId=9d71ae45-df5f-49f7-86f8-e88f54132fa1&RecordIds=01132f6d-ef4a-4014-817e-94a5a19bd52b

Response JSON

{
    "StatusCode": 200,
    "StatusName": "Ok",
    "StatusMessage": "Successful API call",
    "SubmissionId": "9d71ae45-df5f-49f7-86f8-e88f54132fa1",
    "BusinessId": "01132f6d-ef4a-4014-817e-94a5a19bd52b",
    "PayerRef": "Pe123",
    "Form1099Type": "NEC",
    "Form1099Records": {
        "SuccessRecords": [
            {
                "SequenceId": "1",
                "RecordId": "01132f6d-ef4a-4014-817e-94a5a19bd52b",
                "RecipientId": "303b69e7-9fc9-4dd1-a6f2-327fb7b45299",
                "FederalReturn": {
                    "Status": "CREATED",
                    "StatusTs": "2021-10-14 10:58:19 +05:30",
                    "Info": null
                },
               "StateReturns": [
                   {
                     "StateCd": "WV",
                     "Status": "State Filing Order Received",
                     "StatusTs": "2021-08-23 01:45:54 -04:00",
                     "Info": null,
                     "Errors": null
                   },
                   {
                     "StateCd": "ID",
                     "Status": "State Filing Order Received",
                     "StatusTs": "2021-08-23 01:45:54 -04:00",
                     "Info": null,
                     "Errors": null
                   }
                 ] ,    
                "Postal": {
                    "Status": "CREATED",
                    "StatusTs": "2021-10-14 10:58:39 +05:30",
                    "Info": null
                },
                "OnlineAccess": {
                    "Status": "CREATED",
                    "Email": "john@gmail.com",
                    "Info": null
                },
               "ScheduleFiling": {
                    "ScheduledOn": null,
                    "Info": "This service will be available soon"
                }
            }
        ],
        "ErrorRecords": null
    },
    "Errors": null
}

1
2
3
4
5
6
7
8
9
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
51
52
53
54
55

# Transmit

Transmits the Form 1099-NEC return to the IRS. You can Transmit a return successfully only if there are no validation errors in the return.

POST Form1099NEC/Transmit

Request Body

Field	Type	Description
SubmissionId	guid	Unique identifier of a submission
RecordIds	Guid[]	An unique identifier generated by TaxBandits when a 1099-NEC return is created. Mention the 1099-NEC return's Record ID that you want to transmit.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
Form1099Records	object	Pulls the Form 1099 NEC records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form 1099 NEC Records
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
Status	string	Returns the status of the records.
StatusTs	string	Date and Time of the Return Transmission
ErrorRecords	object[]	It will show the detailed information about the error status of Form 1099 NEC Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
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
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

Request JSON

{
  "SubmissionId": "e88e7f1d-7ae5-43b6-99f6-38d85664035a",
  "RecordIds": [
    "63f0aaf2-7b35-487d-a003-0be8b522ef47"
  ]
}

1
2
3
4
5
6

Response JSON

{
  "StatusCode": 200,
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "e88e7f1d-7ae5-43b6-99f6-38d85664035a",
  "Form1099Records": {
    "SuccessRecords": [
      {
        "SequenceId": "1",
        "RecordId": "63f0aaf2-7b35-487d-a003-0be8b522ef47",
        "Status": "Transmitted",
        "StatusTs": "2021-08-23 02:02:19 -04:00",
        "StateReturns": [
          {
            "StateCode": "WV",
            "RecordStatus": "Transmitted"
          },
          {
            "StateCode": "ID",
            "RecordStatus": "Transmitted"
          }
        ]
      }
    ],
    "ErrorRecords": null
  },
  "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# Update

Updates the existing Form 1099 NEC return created in TaxBandits. Use the unique identifiers to refer a particular return. You cannot update a Transmitted return.

PUT Form1099NEC/Update

Request Body

Field	Type	Description
SubmissionManifest	object	SubmissionManifest provides the brief information about a particular submission on the whole. It contains information like Submission ID, Tax Year, IsPostal, IsFederalFiling, IsStateFiling, IsOnlineAccess, IsScheduleFiling & ScheduleFiling service details.
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
TaxYear	string	Tax year of Form 1099 NEC to be filed. Allowed values: "2021"
IsFederalFiling	Boolean	Federal Filing for the return will be enabled when the value is True. The Form 1099-NEC will be sent directly to the IRS.
IsStateFiling	Boolean	State Filing for the return will be enabled when the value is True. Form 1099-NEC forms will be directly filed with the respective recipient states. Note: State Filing will not be created for the states that do not require State filing.
IsPostal	Boolean	Postal Order will be created when the value is set as True. Once the return is Transmitted, Form 1099-NEC Recipient copies will be postal mailed to the recipient's address via USPS. Note: Postal Orders for Foreign Address will not be created.
IsOnlineAccess	Boolean	Online Access will be enabled when the value is set as True. Once the return is Transmitted, an email with the link to the secure TaxBandits portal will be sent to the Recipient. The recipient can provide consent and download Form 1099-NEC Recipient copies from the portal.
IsScheduleFiling	Boolean	When true, schedule filing services will be provided for Form 1099 NEC returns under this submission.
ScheduleFiling	object	Contains preferred date to submit the returns to the IRS. Required only when "IsScheduleFiling" is True.
EfileDate	string	Date of Schedule Filing. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY Example: 10/20/2021 or 10-20-2021.
ReturnHeader	object	Contains information about the Business details.
Business	object	Object to identify the Business Details.
BusinessId	Guid	`Optional` Mention the unique Business ID, if you want to update the information of the Business.
BusinessNm	string	Name of the business Size Range: ..75
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: ..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
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	`Optional` Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Phone number of the business Size Range: 10
PhoneExtn	string	`Optional` Extension of the business phone number Size Range: ..5
Fax	string	`Optional` Fax number of the Business Size Range: 10
BusinessType	string	`Optional` Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: 4 Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
SigningAuthority	object	`Optional` Details of the person who is authorized to sign the return
Name	string	`Optional` Name of the signing authority Size Range: ..35
Phone	string	`Optional` Phone number of the signing authority Size Range: 10
BusinessMemberType	string	`Optional` Business title of the signing authority 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	`Optional` Identifies the kind of employer. Mandatory for W-2 and optional for 1099-NEC and 94X series Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	`Optional` Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-NEC and 94X series Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
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	Employer/Payer's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	Employer/Payer'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	Employer/Payer's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the business
Address1	string	Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer's country Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
ReturnData	object[]	Contains information about the recipient details and Form 1099 NEC details.
RecordId	Guid	Unique Identifier of the Record. Mention the Form 1099-NEC return's Record ID that you want to update. If you do not provide the Record ID, then a new record will be added to the submission.
SequenceId	string	An 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. Size Range: 50
Recipient	object	Object to identify the recipient details.
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient when a Form 1099-NEC return is created. Mention the Form 1099-NEC return's Recipient ID that you want to Update.
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
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.
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.
IsForeign	Boolean	When true, identifies the recipient address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the recipient
Address1	string	Recipient's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city Size Range: ..27
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
ForeignAddress	object	If IsForeign is true, pass foreign address of the recipient
Address1	string	Recipient's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city. Size Range: ..27
ProvinceOrStateNm	string	Recipient's Province or State Name. Size Range: ..30
Country	string	Recipient's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Recipient's Postal Code
Email	string	Recipient's email address. Size Range: 0..40
Fax	string	`Optional` Recipient's Fax number. Size Range: 10
Phone	string	Recipient's Phone Number. Size Range: 10
NECFormData	object	Recipient's Form 1099 NEC information
B1NEC	number	Gets the Nonemployee compensation (NEC) amount of $600 or more. Size Range: 0-9999999999.99
B2IsDirectSales	Boolean	When true, identifies sales of $5,000 or more of consumer products to a person on a buy-sell, deposit commission, or any other commission basis for resale anywhere other than in a permanent retail establishment. Applicable only for Tax year 2021.
B4FedTaxWH	number	Gets the amount of Federal Tax Withheld. Size Range: 0-9999999999.99
IsFATCA	Boolean	When true, identifies a U.S. payer reporting on Form(s) 1099 (including reporting payments on this Form 1099-NEC) to satisfy their foreign financial asset reporting requirement with respect to a U.S. account. Not Applicable for Tax year 2021.
AccountNum	string	Account number of Payer having multiple accounts for a recipient for whom more than one Form 1099-NEC is filed. Size Range: 4..20
Is2ndTINnot	Boolean	When true, identifies a Payer who is notified by the IRS twice within 3 calendar years for providing an incorrect TIN and do not want the IRS to send any more notices.
States	object[]	Contains list of state returns information.
StateCd	string	State Code. 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"
StateIdNum	string	Identification Number of State. Size Range: ..20
StateWH	number	Income tax amount withheld for State . Size Range: 0-9999999999.99
StateReconData	object	Collects State Recon fields specific for each state. Click here, for the description of each state specific Recon fields.
StateIncome	number	Amount of payment for State. Size Range: 0-9999999999.99

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a Business.
PayerRef	string	Unique identifier of the payer.
Form1099Type	string	Denotes the type of 1099 form.
Form1099Records	object	Pulls Form 1099 NEC records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form 1099 NEC Records
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient when a 1099-NEC return is created. You can use this id for your future reference to Update.
AccountNum	string	Account number of Payer having multiple accounts for a recipient for whom more than one Form 1099-NEC is filed. Size Range: 4..20
FederalReturn	object	Returns the record status and StatusTs of federal return.
Status	string	Returns the record status.
StatusTs	string	Returns date and time of return created.
Info	string	Returns information about the Federal Filing service.
StateReturns	object[]	Returns collection of state
StateCd	string	Returns the state code of the state which the return filed.
Status	string	Returns the record status of the state return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the state for which we are not state filing.
Errors	object[]	Shows error information of state returns of Form 1099 NEC
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
Postal	object	Returns the status and StatusTs of postal mailing service for Form 1099 NEC.
Status	string	Returns the status of postal order.
StatusTs	string	Returns the date and time of the postal order created.
Info	string	Returns the information about Postal mailing service.
OnlineAccess	object	Returns the Email address for whom the online access to be given and Status of online access.
Status	string	Returns status of online access for Form 1099 NEC return.
Email	string	Email address for whom the online access to be given.
Info	string	Information about the online access service.
ScheduleFiling	object	Returns the date of the schedule filing.
ScheduledOn	string	Date of the schedule filing to know when the return to be filed to the IRS.
Info	string	Information about Schedule Filing service.
ErrorRecords	object[]	It will show the detailed information about the error status of Form 1099 NEC Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
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
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

Request JSON

{
  "SubmissionManifest": {
    "SubmissionId": "e88e7f1d-7ae5-43b6-99f6-38d85664035a",
    "TaxYear": "2021",
    "IsFederalFiling": true,
    "IsStateFiling": true,
    "IsPostal": true,
    "IsOnlineAccess": true,
    "IsScheduleFiling": true,
    "ScheduleFiling": {
      "EfileDate": "11/12/2021"
    }
  },
  "ReturnHeader": {
    "Business": {
      "BusinessId": "c21df64f-9a6d-4e21-ac67-723aacf1ba48",
      "BusinessNm": "Eastman Kodak Com",
      "PayerRef": "Pe123",
      "TradeNm": "Kodak",
      "IsEIN": true,
      "EINorSSN": "62-7369245",
      "Email": "john@gmail.com",
      "ContactNm": "John",
      "Phone": "1234567890",
      "PhoneExtn": "12345",
      "Fax": "1234567890",
      "BusinessType": "ESTE",
      "SigningAuthority": {
        "Name": "John",
        "Phone": "1234567890",
        "BusinessMemberType": "ADMINISTRATOR"
      },
      "KindOfEmployer": "FederalGovt",
      "KindOfPayer": "REGULAR941",
      "IsBusinessTerminated": true,
      "IsForeign": false,
      "USAddress": {
        "Address1": "1751 Kinsey Rd",
        "Address2": "Main St",
        "City": "Dothan",
        "State": "AL",
        "ZipCd": "36303"
      },
      "ForeignAddress": {
        "Address1": null,
        "Address2": null,
        "City": null,
        "ProvinceOrStateNm": null,
        "Country": null,
        "PostalCd": null
      }
    }
  },
  "ReturnData": [
    {
      "RecordId": "63f0aaf2-7b35-487d-a003-0be8b522ef47",
      "SequenceId": "1",
      "Recipient": {
        "RecipientId": "775acc48-7492-487b-8edc-6c4d9877136f",
        "TINType": "EIN",
        "TIN": "393817572",
        "FirstPayeeNm": "Mark",
        "SecondPayeeNm": "Davis",
        "IsForeign": false,
        "USAddress": {
          "Address1": "1751 Kinsey Rd",
          "Address2": "Main St",
          "City": "Dothan",
          "State": "AL",
          "ZipCd": "36303"
        },
        "ForeignAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "ProvinceOrStateNm": null,
          "Country": null,
          "PostalCd": null
        },
        "Email": "john@gmail.com",
        "Fax": "1234567890",
        "Phone": "1234567890"
      },
      "NECFormData": {
        "B1NEC": 100,
        "B2IsDirectSales": true,
        "B4FedTaxWH": 40.55,
        "IsFATCA": false,
        "Is2ndTINnot": true,
        "AccountNum": "20123130000009000001",
        "States": [
          {
            "StateCd": "WV",
            "StateWH": 257.94,
            "StateIdNum": "99999999",
            "StateIncome": 2900
          },
          {
            "StateCd": "ID",
            "StateWH": 15,
            "StateIdNum": "999999999",
            "StateIncome": 16
          }
        ]
      }
    }
  ],
  "StateReconData": {
    "WV": {
      "FormIT103": {
        "WVWithHoldingID": "99999998",
        "NumOf1099W2": 24,
        "TotalTaxWH1099W2": 404,
        "WHTaxDue": {
          "WVTaxQ1": 101,
          "WVTaxQ2": 101,
          "WVTaxQ3": 101,
          "WVTaxQ4": 101,
          "TotalForYear": 404
        }
      }
    },
    "ID": {
      "Form967": {
        "IDWithholdingID": "999999999",
        "TotWagesW2": 0,
        "TotTaxWHW2": 200,
        "NumOfW2Forms": 0,
        "TotTaxWH1099": 400,
        "NumOf1099Forms": 40,
        "TotNumOf1099W2": 40,
        "NumOf1099WithWH": 30,
        "TotTaxWH": 600,
        "WHTaxPaid": 500,
        "BalanceDue": 100,
        "Overpayment": 0,
        "PenaltyOnBalanceDue": 100,
        "InterestOnBalanceDue": 100,
        "BalanceDuePenaltyInt": 300,
        "LateFilingPenalty": 200,
        "TotBalanceDue": 500,
        "TotOverPayment": 0,
        "Is1099CFSF": true,
        "FilingCycle": "Annual"
      }
    }
  }
}

Response JSON

{
  "StatusCode": 200,
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "e88e7f1d-7ae5-43b6-99f6-38d85664035a",
  "BusinessId": "c21df64f-9a6d-4e21-ac67-723aacf1ba48",
  "PayerRef": "Pe123",
  "Form1099Type": "NEC",
  "Form1099Records": {
    "SuccessRecords": [
      {
        "SequenceId": "1",
        "RecordId": "63f0aaf2-7b35-487d-a003-0be8b522ef47",
        "RecipientId": "775acc48-7492-487b-8edc-6c4d9877136f",
        "AccountNum": "20123130000009000001",
        "FederalReturn": {
          "Status": "CREATED",
          "StatusTs": "2021-08-23 01:50:17 -04:00",
          "Info": null
        },
        "StateReturns": [
          {
            "StateCd": "WV",
            "Status": "CREATED",
            "StatusTs": "2021-08-23 01:50:17 -04:00",
            "Info": null,
            "Errors": null
          },
          {
            "StateCd": "ID",
            "Status": "CREATED",
            "StatusTs": "2021-08-23 01:50:17 -04:00",
            "Info": null,
            "Errors": null
          }
        ],
        "Postal": {
          "Status": "CREATED",
          "StatusTs": "2021-08-23 01:50:17 -04:00",
          "Info": null
        },
        "OnlineAccess": {
          "Status": "CREATED",
          "Email": "john@gmail.com",
          "Info": null
        },
        "ScheduleFiling": {
          "ScheduledOn": null,
          "Info": "This Service will be available soon"
        }
      }
    ],
    "ErrorRecords": null
  },
  "Errors": null
}

1
2
3
4
5
6
7
8
9
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
51
52
53
54
55
56

# Validate

Executes business and data validation checks for the 1099 NEC returns already created in API. Use the Submission ID and Record IDs of the return to validate.

GET Form1099NEC/Validate

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
RecordIds	Guid[]	An unique identifier generated by TaxBandits when a 1099-NEC return is created. Mention the 1099-NEC return's Record ID that you want to Validate.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
Form1099Records	object	Pulls the Form 1099 NEC records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form 1099 Records
SequenceId	string	An 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.
RecordId	Guid	Record ID of the returns that were successfully validated.
Status	string	Returns the status of the records.
StatusTs	string	Date and time of return created.
ErrorRecords	object[]	It will show the detailed information about the error status of Form 1099 Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
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
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

Request JSON

Form1099NEC/Validate?SubmissionId=9d71ae45-df5f-49f7-86f8-e88f54132fa1&RecordIds=01132f6d-ef4a-4014-817e-94a5a19bd52b,eb39714e-f653-4c4d-a53c-07f24f9a9dj5

Response JSON

{
  "StatusCode": 200,
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "9d71ae45-df5f-49f7-86f8-e88f54132fa1",
  "Form1099Records": {
    "SuccessRecords": [
      {
        "SequenceId": "1",
        "RecordId": "15c3caa6-8402-4548-8713-4fcdd2f7d42d",
        "Status": "CREATED",
        "StatusTs": "2021-08-05 06:26:16 -04:00"
      },
      {
        "SequenceId": "2",
        "RecordId": "eb39714e-f653-4c4d-a53c-07f24f9a9dj5",
        "Status": "CREATED",
        "StatusTs": "2021-08-05 06:26:16 -04:00"
      }
    ],
    "ErrorRecords": null
  },
  "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# ValidateForm

Validates the Forms in the request against IRS Business rules and field specification without creating the returns in TaxBandits.

POST Form1099NEC/ValidateForm

Request Body

Field	Type	Description
SubmissionManifest	object	SubmissionManifest provides the brief information about a particular submission on the whole. It contains information like Submission ID, Tax Year, IsPostal, IsFederalFiling, IsStateFiling, IsOnlineAccess, IsScheduleFiling & ScheduleFiling service details.
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
TaxYear	string	Tax year of Form 1099 NEC to be filed. Allowed values: "2021"
IsFederalFiling	Boolean	Federal Filing for the return will be enabled when the value is True. Form 1099-NEC will be sent directly to the IRS.
IsStateFiling	Boolean	State Filing for the return will be enabled when the value is True. Form 1099-NEC will be directly filed with the respective recipient states. Note: State Filing will not be created for the states that do not require State filing.
IsPostal	Boolean	Postal Order will be created when the value is set as True. Once the return is Transmitted, Form 1099-NEC Recipient copies will be postal mailed to the recipient's address via USPS. Note: Postal Orders for Foreign Address will not be created.
IsOnlineAccess	Boolean	Online Access will be enabled when the value is set as True. Once the return is Transmitted, an email with the link to the secure TaxBandits portal will be sent to the Recipient. The recipient can provide consent and download Form 1099-NEC Recipient copies from the portal.
IsScheduleFiling	Boolean	When true, schedule filing services will be provided for Form 1099 NEC returns under this submission.
ScheduleFiling	object	Contains preferred date to submit the returns to the IRS. Required only when "IsScheduleFiling" is True .
EfileDate	string	Date of Schedule Filing. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY Example: 10/20/2021 or 10-20-2021
ReturnHeader	object	Contains information about the Business details.
Business	object	Object to identify the Business Details.
BusinessId	Guid	Unique Identifier of the Business , it will be provided by TaxBandits if the Business is already created .
BusinessNm	string	Name of the business Size Range: ..75
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
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	`Optional` Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Phone number of the business Size Range: 10
PhoneExtn	string	`Optional` Extension of the business phone number Size Range: ..5
Fax	string	`Optional` Fax number of the Business Size Range: 10
BusinessType	string	`Optional` Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: 4 Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
SigningAuthority	object	`Optional` Details of the person who is authorized to sign the return
Name	string	`Optional` Name of the signing authority Size Range: ..35
Phone	string	`Optional` Phone number of the signing authority Size Range: 10
BusinessMemberType	string	`Optional` Business title of the signing authority 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	`Optional` Identifies the kind of employer. Mandatory for W-2 and optional for 1099-NEC and 94X series Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	`Optional` Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-NEC and 94X series Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
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	Employer/Payer's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	Employer/Payer'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	Employer/Payer's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the business
Address1	string	Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer's country Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
ReturnData	object[]	Contains information about the recipient details and Form 1099 NEC details.
SequenceId	string	An 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. Size Range: 50
RecordId	Guid	Unique identifier of a record. Not required when you are creating a return.
Recipient	object	Object to identify the recipient details.
RecipientId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to Update.
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
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.
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.
IsForeign	Boolean	When true, identifies the recipient address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the recipient
Address1	string	Recipient's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city Size Range: ..27
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
ForeignAddress	object	If IsForeign is true, pass foreign address of the recipient
Address1	string	Recipient's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city. Size Range: ..27
ProvinceOrStateNm	string	Recipient's Province or State Name. Size Range: ..30
Country	string	Recipient's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Recipient's Postal Code
Email	string	Recipient's email address. Size Range: 0..40
Fax	string	`Optional` Recipient's Fax number. Size Range: 10
Phone	string	Recipient's Phone Number. Size Range: 10
NECFormData	object	Recipient's Form 1099 NEC information
B1NEC	number	Gets the Nonemployee compensation (NEC) amount of $600 or more. Size Range: 0-9999999999.99
B2IsDirectSales	Boolean	When true, identifies sales of $5,000 or more of consumer products to a person on a buy-sell, deposit commission, or any other commission basis for resale anywhere other than in a permanent retail establishment. Applicable only for Tax year 2021.
B4FedTaxWH	number	Gets the amount of Federal Tax Withheld. Size Range: 0-9999999999.99
IsFATCA	Boolean	When true, identifies a U.S. payer reporting on Form(s) 1099 (including reporting payments on this Form 1099-NEC) to satisfy their foreign financial asset reporting requirement with respect to a U.S. account. Not Applicable for Tax year 2021.
AccountNum	string	Account number of Payer having multiple accounts for a recipient for whom more than one Form 1099-NEC is filed. Size Range: 4..20
Is2ndTINnot	Boolean	When true, identifies a Payer who is notified by the IRS twice within 3 calendar years for providing an incorrect TIN and do not want the IRS to send any more notices.
States	object[]	Contains list of state returns information.
StateCd	string	State Code. 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"
StateIdNum	string	Identification Number of State. Size Range: ..20
StateWH	number	Income tax amount withheld for State . Size Range: 0-9999999999.99
StateIncome	number	Amount of payment for State. Size Range: 0-9999999999.99
StateReconData	object	Collects State Recon fields specific for each state. Click here, for the description of each state specific Recon fields.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a Business.
Form1099Records	object	Pulls Form 1099 NEC records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form 1099 NEC Records
SequenceId	string	An 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.
RecordId	Guid	An unique identifier generated by TaxBandits when a 1099-NEC return is created.
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient when a 1099-NEC return is created. You can use this id for your future reference to Update.
FederalReturn	object	Returns the record status and StatusTs of federal return.
Status	string	Returns the record status.
StatusTs	string	Returns date and time of return created.
Info	string	Returns information about the Federal Filing service.
StateReturns	object[]	Returns collection of state returns information
StateCd	string	Returns the state code of the state for which the return is filed.
Status	string	Returns the record status of the state return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the state for which we are not supporting state filing.
Errors	object[]	Shows error information of state returns of Form 1099 NEC
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
Postal	object	Returns the status and StatusTs of postal mailing service for Form 1099 NEC.
Status	string	Returns the status of postal order.
StatusTs	string	Returns the date and time of the postal order created.
Info	string	Returns the information about Postal mailing service.
OnlineAccess	object	Returns the Email address for whom the online access to be given and Status of online access.
Status	string	Returns status of online access for Form 1099 NEC return.
Email	string	Email address for whom the online access to be given.
Info	string	Information about the online access service.
ScheduleFiling	object	Returns the date of the schedule filing.
ScheduledOn	string	Date of the schedule filing to know when the return to be filed to the IRS.
Info	string	Information about Schedule Filing service.
ErrorRecords	object[]	It will show the detailed information about the error status of Form 1099 NEC Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
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
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

Request JSON

{
   "SubmissionManifest": {
   "SubmissionId": null,
 "TaxYear": "2021",
 "IsFederalFiling": true,
 "IsStateFiling": true,
 "IsPostal": true,
 "IsOnlineAccess": true,    
 "IsScheduleFiling": true,
 "ScheduleFiling": {
     "EfileDate": "12/11/2021"
 }
   },
   "ReturnHeader": {
       "Business": {
           "BusinessId": null,
           "BusinessNm": "Eastman Kodak Com",
           "TradeNm": "Kodak",
           "IsEIN": true,
           "EINorSSN": "00-3387158",
           "Email": "john@gmail.com",
           "ContactNm": "John",
           "Phone": "1234567890",
           "PhoneExtn": "12345",
           "Fax": "1234567890",
           "BusinessType": "ESTE",
           "SigningAuthority": {
               "Name": "John",
               "Phone": "1234567890",
               "BusinessMemberType": "ADMINISTRATOR"
           },
           "KindOfEmployer": "FederalGovt",
           "KindOfPayer": "REGULAR941",
           "IsBusinessTerminated": true,
           "IsForeign": false,
           "USAddress": {
               "Address1": "1751 Kinsey Rd",
               "Address2": "Main St",
               "City": "Dothan",
               "State": "AL",
               "ZipCd": "36303"
           },
           "ForeignAddress": {
               "Address1": null,
               "Address2": null,
               "City": null,
               "ProvinceOrStateNm": null,
               "Country": null,
               "PostalCd": null
           }
       }
   },
   "ReturnData": [
       {
           "RecordId": null,
           "SequenceId": "1",
           "Recipient": {
               "RecipientId": null,
               "TINType": "EIN",
               "TIN": "393814579",
               "FirstPayeeNm": "Mark",
               "SecondPayeeNm": "Davis",
               "IsForeign": false,
               "USAddress": {
                   "Address1": "1751 Kinsey Rd",
                   "Address2": "Main St",
                   "City": "Dothan",
                   "State": "AL",
                   "ZipCd": "36303"
               },
               "ForeignAddress": {
                   "Address1": null,
                   "Address2": null,
                   "City": null,
                   "ProvinceOrStateNm": null,
                   "Country": null,
                   "PostalCd": null
               },
               "Email": "john@gmail.com",
               "Fax": "1234567890",
               "Phone": "1234567890"
           },
           "NECFormData": {
               "B1NEC": 100,
               "B2IsDirectSales":true,
               "B4FedTaxWH": 40.55,
               "IsFATCA": false,
               "Is2ndTINnot": true,
               "AccountNum": "20123130000009000001",
               "States":[
               {
               "StateCd": "PA",
               "StateWH": 15,
               "StateIdNum": "99999999",
               "StateIncome": 16
               },
               {
               "StateCd": "AZ",
               "StateWH": 17,
               "StateIdNum": "99-9999999",
               "StateIncome": 18
               }]
           }
       }
   ]
}

Response JSON

  {
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "Errors": null
}

1
2
3
4
5
6

← Form1099MiscCorrection Form1099NecCorrection →