RequestByURL

RequestByURL

Instead of creating the business details yourself, you can use this endpoint to allow the respective payer or employer to add their own information to the TaxBandits API.

With this endpoint, you can generate a secure URL that can either be:

• Embedded as an iframe within your software or portal
• Shared as a hosted URL for the payer/employer to access directly

Once the payer/employer opens the URL, they can complete and submit their business information on their own.

How it works

1. Authenticate

   Obtain a Bearer token via the OAuth 2.0 flow and include it in all request headers.

2. Call the Business/RequestByUrl Endpoint

   Call the GET Business/RequestByURL endpoint by passing the required request parameters.

   Your request may include:

   • Payee Identifier (PayerRef) — A unique identifier for the payer/employer. This can be any value that helps you uniquely identify the payer/employer in your system, such as a reference number, an account ID, or the payer/employer’s email address.
   • Callback URLs — You can optionally provide callback URLs to redirect the payer/employer after they complete or cancel the submission.
     • ReturnURL: Redirects the payer/employer after they successfully complete the form.
     • CancelURL: Redirects the payer/employer when they cancel the submission.

   Before using a callback URL, make sure it is valid. The API will post a sample JSON to the callback URL, and the URL must return an HTTP 200 response code to remain active. If it does not return a 200 response, the callback URL will be marked inactive.

3. Receive the Secure Business URL

   TaxBandits API will generate a unique, secure BusinessUrl and return it in the response. You can either:

   • Embed this URL in your application using an iframe
   • Display it as a hosted URL for the payer/employer to access directly

4. Get Notified Through Webhook

   Once the payer/employer submits their business information, you will be notified through the Business Complete webhook (if configured). Learn more

GET Business/RequestByURL 

Run in Postman

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

Response Body

Field	Type	Description
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.
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.

Payload

Request Json

Sample	Description	Action
Sample 1	Request with PayerRef and Redirection URLs. Make sure to configure the Business Complete Webhook console.
Sample 2	Request with just the PayerRef and formtype
Sample 3	Request without the PayerRef

Sample 1

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

Response Json

Sample	Description	Action
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.
Response 2	Unique URL will generated for the specific PayerRef and the formtype. The completed form will be saved against a default business.
Response 3	System will throw an error that PayerRef is required.

Response 1

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

Node.js

Python

Java

.NET C#