Skip to main content
Version: 1.7.3

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

Request Body

FieldTypeDescription
TaxYearstringTax year of Form 1099-NEC to be filed.
Allowed values: "2022","2023","2024"
RecordIdGuidUnique identifier of a record.
BusinessobjectPayer Information.
    BusinessIdGuidUnique identifier of the payer. Generated by TaxBandits.
    PayerRefstringUnique identifier of the payer. Set by the client.
    TINTypestringTIN Type of the business.
Allowed values: "SSN,EIN"
    TINstringTaxpayer Identification Number of the business.
Size Range: 9-11
RecipientobjectRecipient Information.
    PayeeRefstringUnique identifier of the recipient. Set by the client.
    RecipientIdGuidUnique identifier of the recipient. Generated by TaxBandits.
    TINTypestringSpecify the TIN type of the recipient.
Allowed values: "SSN,EIN"
    TINstringEnter the nine-digit taxpayer identification number of the Recipient (SSN, ITIN, ATIN, or EIN).
CustomizationobjectBusiness Portal Information.
    BusinessLogoUrlstringOptional Business Logo that will be displayed on the 1099 Retrieval page
Size Range: 1..50
    ReturnUrlstringOptional Return Redirection URL. Set the callback URL to direct the recipient from the 1099 page back to your portal.
Size Range: 1..50
    CancelUrlstringCanceling the Return Redirection URL.
    ExpiryTimenumberNumber of times the link is accessible.

Response Body

FieldTypeDescription
RecipientIdGuidUnique identifier of the recipient.
DistributionUrlstringURL that can be embedded on your portal using Iframe or other means.
Errorsobject[]Collection of errors for the Recipient.
    IdstringReturns the validation error Id
    NamestringName of the validation error
    MessagestringDescription of the validation error

Request Json

{
"TaxYear": "2023",
"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 Json

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