URL Parameterization (Applicable for RequestByBusinessUrl)

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, the TaxBandits API provides a way to track submissions.

How it works

• You can append a PayeeRef parameter—a unique identifier you assign to each payee—to the secure URL.

If the generated SecureURL is: "https://snowda_388311.esignw9.com", you can add PayeeRef as shown below:

"https://snowda_388311.esignw9.com/?payeeref=user001"

• When a payee completes and submits the form, the WhCertificate Status Change webhook will return the same PayeeRef value, allowing you to directly map the submission to the intended vendor.
• This ensures that submissions are associated with the correct vendor.

Common use cases

• Vendor Portal Integration: Embed the secure URL in each vendor’s portal. Dynamically append a unique PayeeRef (e.g., vendor ID or internal reference) after authentication.

  When the vendor completes the form, the webhook response will return the same PayeeRef, ensuring submissions are tied back to the correct vendor profile.

• Email Distribution: Include the secure URL with a PayeeRef in email invitations sent to vendors. Each vendor receives a unique link, enabling direct mapping when they submit their form.

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 +
!	%21
#	%23
$	%24
%	%25
&	%26
'	%27
*	%2A

Character	Encoded Value
(	%28
)	%29
,	%2C
/	%2F
:	%3A
;	%3B
=	%3D
?	%3F

Character	Encoded Value
@	%40
[	%5B
]	%5D
<	%3C
>	%3E
^	%5E
{	%7B
}	%7D

Note:

Special characters such as . _ - ~ do not require encoding.