Skip to main content
Version: 1.6.1

RequestByURL

To complete the payer information for 1099 filing, TaxBandits will supply the URL that can be opened on its own or embedded as an Iframe into a web page or native app. To get the URL, you will have to send a request to our API with a unique Payer Reference Number such as a random number or even an email address (This will be used to identify the payer for future references).

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 Business/RequestByURL API endpoint. If you are trying to embed this link into your web page, this endpoint must be called before you load the page.You will need to supply the following parameters.

    • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API).
    • Payer Reference (Unique information that identifies the Payer). The Payer Reference can be anything that uniquely identifies the payer such as reference number or a random number or even an email address (This will be used to identify the payer for future references).
    • Callback URLs (Optional) - You can set the callback redirection for payer form completion/cancel.
  3. TaxBandits will generate a unique URL and will send the link in the response, which must then be embedded into the page for the payers to click. When clicked, this link will show the Payer Information page with built-in validations.

  4. Once the payer completes the Payer Information page, you will be notified via webhook. The webhook payload will have the payer data such as the Name, Address and EIN/SSN.

GET Business/RequestByURL

Request Body

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

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.

Request 1: Request with PayerRef and Redirection URLs

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

Response 1:

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

Request 2: Request with just the PayerRef and formtype

"business/requestbyurl?payerref=1261452&formtype=form1099"

Response 2:

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

Request 3: Request without the PayerRef

"business/requestbyurl?formtype=form1099"

Response 3: Our system will throw error that PayerRef is required

{  "PayerRef": null,  "BusinessUrl": null,  "Errors": [    {      "Id": "F00-100272",      "Name": "PayerRef",      "Message": "PayerReference is required"    }  ]}