URL Parameterization for RequestByBusinessUrl Method
When using the RequestByBusinessUrl method to collect W-9/W-8 forms, the API generates a common public URL for a specific business (payer) or DBA. This URL can be embedded into your website or shared directly with payees/vendors, allowing them to complete and submit their forms.
Since this method does not inherently identify which vendor submitted a form, TaxBandits API provides a way to track submissions. You can assign a reference to the secure URL corresponding to each payee to ensure accurate tracking. TaxBandits API allows you to do this using PayeeRef, a unique identifier that can be assigned to each payee.
- By appending a PayeeRef parameter to the secure URL, you can associate submissions with specific vendors.
- This URL appended with PayeeRef can be integrated within a vendor's secure portal or included in emails sent to the payees/vendors.
- When a payee or vendor completes and submits the form, the TaxBandits API will return the same PayeeRef value in the webhook response of 'WhCertificate Status Change'.
This ensures that submissions can be directly associated with the intended vendor, streamlining the W-9/W-8 collection process.
Example:
-
If the generated SecureURL is: https://snowda_388311.esignw9.com
-
You can add PayeeRef as shown below: https://snowda_388311.esignw9.com/?payeeref=user001
Key Instructions:
The PayeeRef parameter supports a specific set of allowed special characters and enforces restrictions to ensure proper handling in API requests.
Allowed Characters:
- Alphabets (A-Z, a-z)
- Numbers (0-9)
- Special Characters: !@#$%^&*()_-=[]|:;'<>?,./~`
Restricted Characters:
The following characters are not allowed in PayeeRef:
- +
- " (double quote)
- \ (backslash)
If these characters are found in the input, they will be removed before saving the value.
Encoding Considerations:
When passing the PayeeRef parameter in a URL, certain special characters must be URL-encoded to ensure proper handling. Below is the encoding reference:
| Character | Encoded Value |
|---|---|
| Space | %20 or + (in query parameters) |
| ! | %21 |
| # | %23 |
| $ | %24 |
| % | %25 |
| & | %26 |
| ' | %27 |
| ( | %28 |
| ) | %29 |
| * | %2A |
| , | %2C |
| / | %2F |
| : | %3A |
| ; | %3B |
| = | %3D |
| ? | %3F |
| @ | %40 |
| [ | %5B |
| ] | %5D |
| < | %3C |
| > | %3E |
| ^ | %5E |
| { | %7B |
| } | %7D |
Special characters such as . _ - ~ do not require encoding.