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 

Request Params

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

Request Params

Sample 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/"

Sample 2

Request with just the PayerRef and formtype

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

Sample 3

Request without the PayerRef

"business/requestbyurl?formtype=form1099"

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.

Response JSON

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
}

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
}

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"
    }
  ]
}