Extract
Extract
The WhCertificate Extraction API extracts form data from Form W-9/W-8 series documents using a pre-signed PDF URL.
Pass the pre-signed PDF URL in the request, and the AI-powered extraction service identifies the form type and extracts the relevant field values. Once extraction is complete, the response returns the extracted form data, the average field-level confidence score, TIN Matching results (where applicable), and the fields that need review because they were extracted incorrectly, incompletely, or with uncertainty.
The confidence score is the average extraction accuracy of the individual fields. If every field is extracted without ambiguity, the overall confidence score is 100%. If certain fields need review, the overall score is reduced based on the confidence scores of those fields.
Key Points
- Supported Forms — Extraction is supported for Form W-9 and Form W-8BEN.
- FileId — Get a
FileIdby uploading the document through the Utility/UploadFile endpoint. TheFileIdcan be used only after the upload is complete. - TIN Matching — Set
IsTINMatchingto TRUE to automatically trigger IRS TIN Matching once extraction is complete. TIN Matching is only applicable for the W-9 form type. - Save as Recipient — Set
IsSaveAddressBookto TRUE to automatically save the recipient from the extracted data. - Low Confidence Fields — Fields listed in
LowConfidenceFieldscould not be detected, or were extracted with low confidence, and should be reviewed manually.
POST WhCertificate/Extract Request Body
| Field | Type | Description |
|---|---|---|
| Requester | Object | Collects the Requester identifier. It can be the Business Id / PayerRef generated by TaxBandits. If neither is provided, the default Business will be assumed as the Requester. |
| PayerRef | String | Optional A unique payer identifier that you will assign while requesting the payer information using the endpoint Business/RequestByURL. Size Range: 1-50 |
| BusinessId | Guid | Optional A unique business identifier generated by TaxBandits after you create a business in your account using the Business endpoint. If you do not provide a BusinessId in the request, the URL will be generated against the default business, i.e., the first business created in your account. |
| WhCertificateRecords | Object | Information about the pre-signed withholding certificate file to be extracted. |
| FormType | String | Withholding certificate form type.Allowed values"W9", "W8BEN" |
| PayeeRef | String | Optional Your unique identifier for the recipient. Max 50 characters |
| FileId | GUID | Unique identifier generated by TaxBandits for the file. |
| FilePath | String | File path of the file. |
| FileByte | byte[] | Byte array of the file |
| IsTINMatching | Boolean | Optional Set to TRUE to automatically trigger IRS TIN Matching once the W-9 form extraction is complete. Note: TIN Matching is only applicable for the W-9 form type. |
| IsSaveAddressBook | Boolean | Optional Set to TRUE to automatically save the recipient from the extracted data. |
Response Body
| Field | Type | Description |
|---|---|---|
| SubmissionId | GUID | Unique identifier of a submission. |
| FileId | String | Pre-signed file URL of the withholding certificate form. |
| FormType | String | Withholding certificate form type. |
| RecipeintId | GUID | A unique reference ID for the submission, used to identify a particular record. |
| PayeeRef | String | Your unique identifier for the recipient, as provided in the request. |
| FormData | Object | Extracted withholding certificate form data of the recipient. |
| Line1Nm | String | Name as shown on the income tax return. |
| Line2Nm | String | Business name/disregarded entity name, if different from Line 1 Name. |
| FirstNm | String | First name of the individual. |
| MiddleNm | String | Middle name of the individual. |
| LastNm | String | Last name of the individual. |
| Suffix | String | Suffix of the individual. |
| TINType | String | TIN type of the recipient. |
| TIN | String | Recipient's TIN. |
| Address | Object | Address information of the recipient. |
| Address1 | String | Street address or PO Box. |
| Address2 | String | Suite or apartment number. |
| City | String | Recipient's city. |
| ProvinceOrState | String | Recipient's province or state name. |
| ZipCd | String | Recipient's ZIP code. |
| Country | String | Recipient's 2-character country code. |
| AccountNum | String | Recipient's account number. You can use this field to enter any identification number you have for the recipient. |
| FederalTaxClassification | String | U.S. Federal Tax Classification of the person whose name is entered on Line 1. |
| OtherDesc | String | U.S. Federal Tax Classification of the individual or entity on Line 1, when 'Other' is selected as the Federal Tax Classification. |
| IsLine3b | Boolean | If TRUE, identifies that the recipient is either a partnership, trust, or estate that has foreign partners, owners, or beneficiaries and the recipient is providing this form to a partnership, trust, or estate in which they have an ownership interest (or) received a Form W-8 from any partner, owner, or beneficiary establishing foreign status (or) received a Form W-9 from any partner, owner, or beneficiary that has checked the box on line 3b. |
| ExemptPayeeCd | String | This code identifies the recipient as exempt from backup withholding. |
| ExemptFromFATCA | String | This code identifies recipients that are exempt from reporting under FATCA. |
| IsBackUpWH | Boolean | When TRUE, identifies that the recipient is subject to backup withholding. (The completed Form W-9 PDF will have item 2 under Part II crossed out.) When FALSE, identifies that the recipient is not subject to backup withholding. |
| IsDAExemptBroker | Boolean | When TRUE, identifies the recipient as exempt from information reporting as a U.S. digital asset broker within the meaning of Regulations section 1.6045-1(g)(4)(i)(A)(1). |
| NmOfIndividual | Object | Name of the foreign individual. |
| FirstNm | String | First name of the individual. |
| MiddleNm | String | Middle name of the individual. |
| LastNm | String | Last name of the individual. |
| Suffix | String | Suffix of the individual. |
| CitizenOfCountry | String | Recipient's country of citizenship. |
| USTINType | String | TIN type of the recipient. |
| USTIN | String | Recipient's TIN. |
| ForeignTIN | String | Foreign TIN of the recipient. |
| IsFTINNotLegallyRequired | Boolean | When TRUE, indicates that the beneficial owner on line 1 is not legally required to obtain an FTIN from their jurisdiction of residence. |
| ReferenceNum | String | Recipient's reference number. You can use this field to enter any identification number you have for the recipient. |
| DOB | String | Date of birth of the recipient. |
| ExpiryDate | String | Date of form expiration. |
| PermanentAddress | Object | Recipient's permanent address. |
| Address1 | String | Street address or PO Box. |
| Address2 | String | Suite or apartment number. |
| City | String | Recipient's city. |
| ProvinceOrState | String | Recipient's province or state name. |
| ZipCd | String | Recipient's ZIP code. |
| Country | String | Recipient's 2-character country code. |
| MailingAddress | Object | Recipient's mailing address. |
| Address | Object | Address information of the recipient. |
| Address1 | String | Street address or PO Box. |
| Address2 | String | Suite or apartment number. |
| City | String | Recipient's city. |
| ProvinceOrState | String | Recipient's province or state name. |
| ZipCd | String | Recipient's ZIP code. |
| Country | String | Recipient's 2-character country code. |
| W8TaxBenefits | Object | Tax treaty benefits. |
| BeneficiaryCountry | String | Country where the recipient claims to be a resident for income tax treaty purposes. |
| ClaimingProvArticlePara | String | Article and paragraph of the treaty benefits. |
| RateOfWH | String | Rate of withholding. |
| TypeOfIncome | String | Type of income for which the recipient claims the treaty benefits. |
| AdditionalConditions | String | Additional conditions from the tax treaty benefits. |
| Signature | Object | Signature of the recipient. |
| SignerNm | String | Name of the signer. |
| Status | String | Status of the extraction. |
| StatusTs | String | Timestamp of the extraction status. |
| AvgConfidenceScore | String | Average confidence score of the extracted form data. |
| LowConfidenceFields | String [] | List of fields with low confidence scores that require manual review, including fields that the system could not detect or extract from the provided document. |
| Info | String | Information about the extraction. |
| TINMatching | Object | TIN Matching information. |
| Status | String | TIN Matching status. |
| StatusTs | String | Timestamp of the TIN Matching status. |
| Errors | Object [] | Detailed error information for TIN Matching. |
| Id | String | Error ID number assigned by TaxBandits. It is unique for each error. |
| Name | String | Name of the errored node. |
| Message | String | Error message. |
| Errors | Object [] | Top-level request errors, returned when the entire request cannot be processed. |
| Id | String | Validation error code. |
| Name | String | Name of the validation rule that failed. |
| Message | String | Description of what went wrong and how to fix it. |
Payload

Go Lang
Node.js
Python
.NET C#

Ruby
Java

cURL
| Sample | Description | Action |
|---|---|---|
| Sample 1 | Extracts data from a Form W-9 using the FileId returned by the Utility/UploadFile endpoint, triggers TIN Matching, and saves the recipient to the address book. | |
| Sample 2 | Extracts data from a Form W-9 using a publicly accessible PDF URL passed in FilePath, triggers TIN Matching, and saves the recipient to the address book. | |
| Sample 3 | Extracts data from a Form W-9 by passing the PDF content as a Base64-encoded string in FileByte, triggers TIN Matching, and saves the recipient to the address book. | |
| Sample 4 | Extracts data from a pre-signed Form W-8BEN and saves the recipient to the address book. TIN Matching is not applicable for W-8BEN. | |
| Sample 5 | Extracts data from a Form W-8BEN using a publicly accessible PDF URL passed in FilePath, and saves the recipient to the address book. TIN Matching is not applicable for W-8BEN. | |
| Sample 6 | Extracts data from a Form W-8BEN by passing the PDF content as a Base64-encoded string in FileByte, and saves the recipient to the address book. TIN Matching is not applicable for W-8BEN. |
Sample 1
{
"Requester": {
"BusinessId": "d01d7c56-e180-427a-85e1-22d17a69a237",
"PayerRef": null
},
"WhCertificateRecords": {
"FormType": "W9",
"PayeeRef": "PAYEE-001",
"FileId": "A7B9C123-4567-4890-ABCD-123456789012",
"FilePath": null,
"FileByte": null
},
"IsTINMatching": true,
"IsSaveAddressBook": true
}
| Sample | Description | Action |
|---|---|---|
| 200 | Success Response - Sample response for a successful Form W-9 extraction. The response returns the extracted form data, the average confidence score, and the TIN Matching order status. | |
| 400 | Bad Request Response - You'll get the below response when the document cannot be extracted, for example, when the uploaded file does not match the requested form type. | |
| 401 | Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials. |
Response: 200
{
"SubmissionId": "ee589b93-942c-4be3-8a19-cefb73978c94",
"FileId": null,
"FormType": "W9",
"RecipientId": "50041e2e-0be3-491e-a26a-073fde47cfc4",
"PayeeRef": "48155909",
"FormData": {
"Line1Nm": "Jordan M. Ellis",
"Line2Nm": "Ellis Design Studio",
"FirstNm": "Jordan",
"MiddleNm": "M.",
"LastNm": "Ellis",
"Suffix": null,
"TINType": "SSN",
"TIN": "563-54-7391",
"Address": {
"Address1": "4821 Maple Ave, Apt 3B",
"Address2": null,
"City": "Austin",
"ProvinceOrState": "TX",
"ZipCd": "78701",
"Country": null
},
"AccountNum": "ACCT-48213377",
"FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
"IsLine3b": false,
"ExemptPayeeCd": null,
"ExemptFromFATCA": null,
"IsBackUpWH": false,
"IsDAExemptBroker": false,
"SignerName": "Jordan M. Ellis",
"SignedDate": "11/19/2026"
},
"Status": "EXTRACTION_COMPLETE",
"StatusTs": "2026-11-19 02:27:07 -04:00",
"AvgConfidenceScore": "95",
"LowConfidenceFields": [],
"Info": null,
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2026-11-19 02:27:16 -04:00",
"Errors": null
},
"Errors": null
}
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "<APIURL>/v2.0.0/WhCertificate/Extract"
method := "POST"
payload := strings.NewReader(`{
"WhCertificateRecords": {
"FormType": "W9",
"PayeeRef": "PAYEE-001",
"FileId": "2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D49"
},
"IsTINMatching": true,
"IsSaveAddressBook": true
}`)
client := &http.Client{}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Authorization", "<ACCESS_TOKEN>")
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println("Status:", res.Status)
fmt.Println(string(body))
}
const axios = require('axios');
let data = JSON.stringify({
"WhCertificateRecords": {
"FormType": "W9",
"PayeeRef": "PAYEE-001",
"FileId": "2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D49"
},
"IsTINMatching": true,
"IsSaveAddressBook": true
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: '<APIURL>/v2.0.0/WhCertificate/Extract',
headers: {
'Authorization': '<ACCESS_TOKEN>',
'Content-Type': 'application/json'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import http.client
import json
conn = http.client.HTTPSConnection("<APIURL>")
payload = json.dumps({
"WhCertificateRecords": {
"FormType": "W9",
"PayeeRef": "PAYEE-001",
"FileId": "2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D49"
},
"IsTINMatching": True,
"IsSaveAddressBook": True
})
headers = {
'Authorization': '<ACCESS_TOKEN>',
'Content-Type': 'application/json'
}
conn.request("POST", "/v2.0.0/WhCertificate/Extract", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "<APIURL>/v2.0.0/WhCertificate/Extract");
request.Headers.Add("Authorization", "<ACCESS_TOKEN>");
var content = new StringContent("{\r\n\t\"WhCertificateRecords\": {\r\n\t\t\"FormType\": \"W9\",\r\n\t\t\"PayeeRef\": \"PAYEE-001\",\r\n\t\t\"FileId\": \"2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D49\"\r\n\t},\r\n\t\"IsTINMatching\": true,\r\n\t\"IsSaveAddressBook\": true\r\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
require "uri"
require "json"
require "net/http"
url = URI("<APIURL>/v2.0.0/WhCertificate/Extract")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = "<ACCESS_TOKEN>"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"WhCertificateRecords": {
"FormType": "W9",
"PayeeRef": "PAYEE-001",
"FileId": "2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D49"
},
"IsTINMatching": true,
"IsSaveAddressBook": true
})
response = https.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n\t\"WhCertificateRecords\": {\r\n\t\t\"FormType\": \"W9\",\r\n\t\t\"PayeeRef\": \"PAYEE-001\",\r\n\t\t\"FileId\": \"2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D49\"\r\n\t},\r\n\t\"IsTINMatching\": true,\r\n\t\"IsSaveAddressBook\": true\r\n}");
Request request = new Request.Builder()
.url("<APIURL>/v2.0.0/WhCertificate/Extract")
.method("POST", body)
.addHeader("Authorization", "<ACCESS_TOKEN>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
curl --location '<APIURL>/v2.0.0/WhCertificate/Extract' \
--header 'Authorization: <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"WhCertificateRecords": {
"FormType": "W9",
"PayeeRef": "PAYEE-001",
"FileId": "2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D49"
},
"IsTINMatching": true,
"IsSaveAddressBook": true
}'