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?

1. 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](TaxBandits OAuth authentication API) for more information on JWT authentication and how to integrate with the subsequent requests.

2. 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](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.

3. 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.

Request JSON

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

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

Response JSON

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

{
   "RecipientId": "36b96057-3a9d-4c4f-a9d1-f8b83cf4acc4",
   "DistributionUrl": "https://testonlineaccess.taxbandits.com/?uid=603bd6ba-cebd-4772-9fa9-6409529513f1",
   "Errors": null
}