Skip to main content
Version: 1.7.0

RequestByURL

Instead of creating the business by yourself, you can have the respective payer/employer submit the details on their own for 1099 filing using the RequestByUrl method.

Using this endpoint, you can obtain a secure URL that can be embedded as an iframe on your software or portal. Upon clicking the URL, the payer/employer can complete their information by themselves. You can configure the ‘Business Complete’ webhook to get notified once the payer/employer submits the details.

How does this work?

  1. Call the [Get] Business/RequestByURL endpoint by providing the following parameters:

    • Access Token in the header as Bearer Token (generated using TaxBandits OAuth authentication API).
    • Payer Reference (A unique identifier of the payer) - This can be anything that uniquely identifies the payer/employer, such as a reference number or even their email address (This will be used to identify the payer for future references).
    • Callback URLs (Optional) - Set the URLs to which you want the payers/employers to be redirected once they complete/cancel the submission.

    Note: Please ensure that the callback URL is valid, as the API will post a sample JSON. The callback URL is expected to return an HTTP 200 response code in order to remain active. If not, the callback URL will be inactive.

  2. TaxBandits API will generate a unique secure URL and send it in the response, which can be embedded into the page or shown by itself (Hosted Solution). Upon clicking the URL, the payer/employer can complete and submit their information.

  3. You will be notified via Webhook whenever the payer/employer completes their information. The payer/employer data, such as name, address, and EIN/SSN, will also be included in the webhook payload.

Refer to Business Complete webhook to learn on how to set up the webhook URLs and for a sample payload.

GET Business/RequestByURL 
Run in Postman

Request Params

FieldTypeDescription
PayerRefStringAn unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API.Size Range: 1-50
FormTypeStringA Type of Form for requesting Business URL.Allowed values: "form1099"
ReturnURLStringOptional Return Redirection URL. Set the callback URL redirection once the payer completes filling the form.Size Range: ..150
CancelURLStringOptional Cancel Redirection URL. Set the callback URL when the payer clicks the cancel button on the Payer Information page.
Note: If you do not provide the Cancel Callback Redirection URL, the cancel button will not be shown to the payer.Size Range: ..150

Request Params

Request with PayerRef and Redirection URLs. Make sure to configure the Business Complete Webhook console.

"business/requestbyurl?payerref=126145&formtype=form1099&returnurl=https://example.com/&cancelurl=https://example.com/"

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
PayerRefstringUnique identifier of the payer.
BusinessUrlstringURL that can be accessed on its own or embedded on the client's website using Iframe or other means.
ErrorsObjectShows error information. This object will list the errors in the request parameters.

Response JSON

Distinctive URL is generated for specific PayerRef to fill and complete the business form. When a Payer submits the form, the "Business Complete" webhook payload will include the status data.

{
"PayerRef": "126145",
"BusinessUrl": "https://testlinks.taxbandits.io?uId=befff9e5-5e52-48b0-81bf-6f960e2bd58e",
"Errors": null
}