RequestDistUrl

RequestDistUrl

This endpoint can be used to request a unique, hosted URL from which recipients can securely view and download their 1099-NEC forms. The logo and redirection URLs can also be customized to match your branding.

Key points

• This endpoint is specifically for the Hosted API URL method, which enables electronic distribution of forms to recipients.
• It can only be called once the 1099-NEC form has been successfully transmitted for the recipient.

How it works

1. OAuth 2.0 Authentication

The first step is to call the Auth method to obtain an access token. Include this access token in the request header as the Bearer token.

Refer to OAuth 2.0 Authentication for details on JWT authentication and how to integrate it with subsequent requests.

2. Request Distribution URL

Next, call the [POST] Form1099NEC/RequestDistUrl endpoint. If you are embedding this link into your web page, make sure you call this endpoint before the page loads.

The required parameters include:

• Access Token - Pass in the header as a Bearer Token
• Recipient Id - A unique identifier of the recipient (RecipientId). This is provided in:
  • The webhook response after Form W-9 completion, and
  • The response of the Form 1099 Create endpoint.
• Business Logo and Callback URLs - Add your logo to the 1099 retrieval page and define a redirection URL where you want the recipients to be redirected after downloading the 1099.

3. URL Generation

TaxBandits will generate a unique URL and return it in the API response. You can embed this URL in your portal or display it directly as a hosted solution for your recipients.

When the recipient clicks the link, they’ll be redirected to a page with a consent form. They must agree to receive their 1099 electronically before they can download it.

POST Form1099NEC/RequestDistUrl 

Run in Postman

Request Body

Field	Type	Description
TaxYear	string	Tax year of Form 1099-NEC to be filed. Allowed values "2023","2024","2025"
RecordId	Guid	A unique identifier of a record.
Business	object	Payer Information.
BusinessId	Guid	A unique identifier of the payer. Generated by TaxBandits.
PayerRef	string	A unique identifier of the payer set by you. Size Range: ..50
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	A unique identifier of the recipient set by you. Size Range: ..50
RecipientId	Guid	A 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). Size Range: 9-11
Customization	object	Contains brand customization details.
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	A 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

Payload

Request Json

{
    "TaxYear": "2025",
    "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
}

Node.js

Python

Java

.NET C#