Collecting W-9s, W-8BENs, and W-8BEN-Es on Your Site

Goal of this guide

Using Avalara 1099 & W-9's low-code embedded document collection tool, collect a W-9/W-8 identified by your chosen reference ID on a webpage you control.

Prerequisites

The guide takes less than 15 minutes to complete once you are ready with:

• A Avalara 1099 & W-9 account with a free trial subscription for collecting W-9s, W-8BENs, and W-8BEN-Es
• API access (see Quick Start)
• Ability to modify the source code of a local HTML file

Production requirements

To develop a production solution you will also need:

• A suitable subscription for collecting W-9s, W-8BENs, and W-8BEN-Es
• From your application server:
  • Ability to look up the meaningful-to-you reference ID of the current user
  • Ability to make HTTPS JSON:API requests and dynamically incorporate the results in generated HTML or in your own API response to your client-side JavaScript's HTTPS request

Download the example HTML page

Download the following simple HTML document and save it as w9-example.html.

Open the saved w9-example.html file in your code editor of choice and in a web browser.

Authorize the API Documentation

Open our API Documentation in a new window or tab and keep it open. Click the green Authorize button on the right and enter the API token you saved from "Get API access" step 2.

Get the data you need to use the API

1. In the Avalara 1099 & W-9 web application, sign in and then click the "W-9" link highlighted in green in the navigation at the top of the page, or go there directly.
2. First time?
   1. Click "Start 7 Day Trial"
   2. Complete the form to create a new Company and click Save. This is the entity that requests and collects W-9 forms. All fields not marked "Optional" are required, but the values can be made up for testing purposes.
   3. Copy the JSON from the "Collect W-9s/W-8s on Your Website" card.
3. Already have a Company record?
   1. Click the name of the company
   2. Click "Request Forms" and select "W-9" in the pulldown menu
   3. Copy the JSON from the "Collect W-9s/W-8s on Your Website" card.

Use the API to create a form_request record

1. Back in the API Documentation window, click to open the Create form request action.
2. Click the "Try it out" button on the right.
3. Delete the example contents of the "Request body" text area and paste the JSON you copied at the end of the previous section. Replace YOUR_ID_FOR_VENDOR with any string value.
4. Click the large blue "Execute" button.
5. You should get a 201 Created response. Scroll past the CURL code to the "Server response" section and copy the entire "Response body". You should see your chosen reference_id in the response.

On line 8 of w9-example.html, remove `REPLACE ME` and paste the entire response body in its place. Save, and reload the page in your web browser.

This step simulates a server-side process creating a form_request during page rendering and including the information in the generated HTML. With slightly different client-side JavaScript code, you could instead create the form_request lazily, as an API response to an XHR.

Collect an example W-9

1. In your web browser, click the "Fill out W-9" button.
2. Enter sample information in the form, then press "Sign & Close" at the end (Check the expected API Response above).
3. See the page update with the date and time you signed.
4. Access the W-9 UI and click on your test company name in the list of companies. The list of forms that appears includes the form you just complete.

Note: you can complete the form again if you don't leave the page, but if you leave and return or reload the page, you will not be able successfully to complete the form again: the form_request has already been used.

To complete another form, you'll need to create a new form_request and edit w9-example.html page again.

Embedded Component Response

After a W-9 is submitted you can see in your browser console or as a result of your API call the following JSON response with TIN match status, signed_at information, etc. As you can see, you are able to record the timestamp of when they signed/submitted the form as well as the TIN Match status.

The signed_pdf property is the URL of PDF representation of just-signed form. Integrations may use this value to offer a "download for your records" function after a vendor completes and signs a form. Link expires at the same time as this FormRequest, i.e. 3,600 seconds (1 hour). Treat the format of this URL as opaque and expect it to change in the future.

Embedded Component Response Statuses

After you submit a W-9 form these are the possible statuses regarding the TIN match:

Next steps

1. Try creating and using another form_request with a different reference_id.
2. Try creating and using another form_request with the same reference_id. The page displays your last-signed date and time immediately. You could use this information to tweak the language on the page or decide whether completing the form is necessary at all.
3. Try creating and using another form_request with a different form_type, such as 'W-8BEN'.
4. Use the Create form request action of the Avalara 1099 & W-9 API from your application server so you can develop your page without manually creating and pasting new form_request JSON.