Extend your software with TaxBandits IRS E-file API Integration

Skip to main content
Version: 1.6.1

Post

How does this work?

  1. Like any other TaxBandits API Endpoint, the first step is to call the Auth method to get the access token. This access token must be supplied in the request header as the ‘Bearer‘ token. Refer to OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.

  2. The second step is to call the Form1099Transactions Post with the following values.

    • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API)

    • Business - Specify the payer from whom the Transactions were made. Any one of the following unique identifiers of the business (Payer) is mandatory.

      • Payer Reference - This identifier is specified by the client while using the endpoint Business/RequestByUrl.
      • BusinessId - This ID is generated by Taxbandits and returned in the response of Business/Create and Business/RequestByUrl endpoints. Refer to the Business endpoint to learn more about creating a Business in TaxBandits and retrieving the Business Id.
      • TIN - Use Business TIN as an alternate identifier if you have not saved the Payer Reference or BusinessId.
    • Recipients - Specify the recipients to whom the Transactions were made. Any one of the following unique identifiers of the recipient is mandatory.

      • PayeeRef - This identifier is specified by the client while using the endpoint FormW9/RequestByUrl. Refer Form W-9 endpoint to know more about Form W-9 in TaxBandits API.
      • RecipientId - This ID is generated by Taxbandits and returned in the webhook responses of Form W-9 and TIN Matching endpoints. The RecipientId is also returned in the 1099 (MISC, NEC) create response.
      • TIN - Use Business TIN as an alternate identifier if you have not saved the PayeeRef or RecipientId.
    • Transactions (Txns) - Transactions made by the payer to recipient.

      • SequenceID - The SequenceId will act as a unique identifier for the transaction.
      • TxnDate - Date the transaction was made.
      • TxnAmt - Transaction amount in dollars.
      • WHAmt - Amount withheld from the Transaction amount.

Key Points

  • Transactions from multiple payers to multiple recipients can be posted in a single submission.
  • The Transactions already posted cannot be edited. Instead use the Delete endpoint to delete an existing submission and post a new submission.
POST Form1099Transactions

Request Body

FieldTypeDescription
TxnDataobject[]This Object contains the Payer, Recipient and Transaction details.
    BusinessobjectPayer Information. Either PayerRef, BusinessId or TIN is mandatory.
        PayerRefStringUnique identifier of the payer. Set by the client in the endpoint Business/RequestByUrl.
        BusinessIdGuidTaxBandits Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
        TINTypeStringTIN Type of the business.
Allowed values: "SSN", "EIN"
        TINStringTaxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11
    Recipientsobject[]Recipient Information. Either PayeeRef, RecipientId or TIN is mandatory.
        PayeeRefStringUnique identifier of the recipient. Set by the client.
        RecipientIdGuidUnique identifier of the recipient.
        TINTypeStringTIN Type of the recipient.
Allowed values: "SSN", "EIN"
        TINStringTaxpayer Identification Number. Use this as an alternative for RecipientId or PayeeRef.
Size Range: 9-11
        Txnsobject[]Collection of Transactions.
    SequenceIDStringOptional The SequenceId will act as a unique identifier for the transaction. TaxBandits will throw an error when there is an API request with a SequenceId that was previously sent. The SequenceId is an optional node.
It can be used to eliminate any chance of duplicate transaction submission.
Size Range: ..50
        TxnDateStringDate of transaction. In the format mm/dd/yyyy or mm-dd-yyyy.
        TxnAmtStringTransaction Amount.
        WHAmtStringOptional Amount withheld.

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
StatusMsgStringStatus Message.
StatusTsStringTime Stamp of the status.
ErrorsobjectShows error information. This object will list the errors in the request parameters.

Request 1 : Post Transaction with BusinessId and RecipientId, with no errors.

{  "TxnData": [    {      "Business": {        "PayerRef": "Be8523",        "BusinessId": "50e6e084-6c22-47a4-8a4e-018fd34eab42",        "TINType": null,        "TIN": null      },      "Recipients": [        {          "PayeeRef": "Pe123",          "RecipientId": "43931da4-ccec-4054-81b5-7ca7249f3891",          "TINType": null,          "TIN": null,          "Txns": [            {              "SequenceId": "1",              "TxnDate": "09/04/2020",              "TxnAmt": "178.25",              "WHAmt": "49.92"            },            {              "SequenceId": "2",              "TxnDate": "08/03/2020",              "TxnAmt": "108.26",              "WHAmt": "28.91"            },            {              "SequenceId": "3",              "TxnDate": "02/03/2020",              "TxnAmt": "138.26",              "WHAmt": "35.44"            }          ]        }      ]    }  ]}

Response 1

{  "SubmissionId": "7f54c788-5673-4cc2-afc2-d5933b54bc37",  "StatusMsg": "Transactions saved successfully",  "StatusTs": "2021-09-16 07:13:51 -04:00",  "Errors": null}

Request 2 : Post Transaction sample with errors.

{ "TxnData": [   {     "Business": {       "PayerRef": null,       "BusinessId": "1231 12",       "TINType": null,       "TIN": null     },     "Recipients": [       {         "PayeeRef": "api6",         "RecipientId": "43931da4-ccec-4054-81b5-7ca7249f3891",         "TINType": null,       "TIN": null,         "Txns": [           {             "SequenceId": null,             "TxnDate": "23/11/2020",             "TxnAmt": "358.25",             "WHAmt": "44"           }         ]

       }           ]   } ]}

Response 2

{ "SubmissionId": null, "StatusMsg": "Error occurred", "StatusTs": null, "Errors": [     {       "Id": "F73-100001",       "Name": "TxnData[1].Business.BusinessId",       "Message": "BusinessId is invalid"     },     {       "Id": "F73-100002",       "Name": "TxnData[1].Recipients[0].Txns[2].TxnDate",       "Message": "TxnDate must be in valid date format(MM/dd/yyyy)"     }   ]}