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. Call the [Get] Business/RequestByURL endpoint. If you are trying to embed this link into your web page, this endpoint must be called before you load the page. 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. 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 the API doesn’t return a 200 response code, then the callback URL will go inactive. 

2. TaxBandits API will generate a unique URL and send the link in the response, which must then be embedded into the page or shown by itself (Hosted Solution) for the Payer to click. When clicked, the Payer will be provided with the Payer Information page with built-in validations. 

3. You will be notified via webhook whenever the payer completes the Payer Information page. The payer data, such as name, address, and EIN/SSN, will 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

Request Body

Field	Type	Description
PayerRef	String	An 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
FormType	String	A Type of Form for requesting Business URL.Allowed values: "form1099"
ReturnURL	String	Optional Return Redirection URL. Set the callback URL redirection once the payer completes filling the form.Size Range: ..150
CancelURL	String	Optional 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

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
PayerRef	string	Unique identifier of the payer.
BusinessUrl	string	URL that can be accessed on its own or embedded on the client's website using Iframe or other means.
Errors	Object	Shows error information. This object will list the errors in the request parameters.

Request 1: 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 1: 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
}

Request 2: Request with just the PayerRef and formtype

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

Response 2: Unique URL will generated for the specific PayerRef and the formtype. The completed form will be saved against a default business.

{
  "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: System will throw an error that PayerRef is required.

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