Skip to main content
Version: 2.0.0

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 FileId by uploading the document through the Utility/UploadFile endpoint. The FileId can be used only after the upload is complete.
  • TIN Matching — Set IsTINMatching to 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 IsSaveAddressBook to TRUE to automatically save the recipient from the extracted data.
  • Low Confidence Fields — Fields listed in LowConfidenceFields could not be detected, or were extracted with low confidence, and should be reviewed manually.
POST WhCertificate/Extract 

Request Body

FieldTypeDescription
RequesterObjectCollects 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.
    PayerRefStringOptional A unique payer identifier that you will assign while requesting the payer information using the endpoint Business/RequestByURL.
Size Range: 1-50
    BusinessIdGuidOptional 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.
WhCertificateRecordsObjectInformation about the pre-signed withholding certificate file to be extracted.
   FormTypeStringWithholding certificate form type.
Allowed values

"W9", "W8BEN"

   PayeeRefStringOptional Your unique identifier for the recipient.
Max 50 characters
   FileIdGUIDUnique identifier generated by TaxBandits for the file.
   FilePathStringFile path of the file.
   FileBytebyte[]Byte array of the file
IsTINMatchingBooleanOptional 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.
IsSaveAddressBookBooleanOptional Set to TRUE to automatically save the recipient from the extracted data.

Response Body

FieldTypeDescription
SubmissionIdGUIDUnique identifier of a submission.
FileIdStringPre-signed file URL of the withholding certificate form.
FormTypeStringWithholding certificate form type.
RecipeintIdGUIDA unique reference ID for the submission, used to identify a particular record.
PayeeRefStringYour unique identifier for the recipient, as provided in the request.
FormDataObjectExtracted withholding certificate form data of the recipient.
   Line1NmStringName as shown on the income tax return.
   Line2NmStringBusiness name/disregarded entity name, if different from Line 1 Name.
   FirstNmStringFirst name of the individual.
   MiddleNmStringMiddle name of the individual.
   LastNmStringLast name of the individual.
   SuffixStringSuffix of the individual.
   TINTypeStringTIN type of the recipient.
   TINStringRecipient's TIN.
   AddressObjectAddress information of the recipient.
      Address1StringStreet address or PO Box.
      Address2StringSuite or apartment number.
      CityStringRecipient's city.
      ProvinceOrStateStringRecipient's province or state name.
      ZipCdStringRecipient's ZIP code.
      CountryStringRecipient's 2-character country code.
   AccountNumStringRecipient's account number. You can use this field to enter any identification number you have for the recipient.
   FederalTaxClassificationStringU.S. Federal Tax Classification of the person whose name is entered on Line 1.
   OtherDescStringU.S. Federal Tax Classification of the individual or entity on Line 1, when 'Other' is selected as the Federal Tax Classification.
   IsLine3bBooleanIf 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.
   ExemptPayeeCdStringThis code identifies the recipient as exempt from backup withholding.
   ExemptFromFATCAStringThis code identifies recipients that are exempt from reporting under FATCA.
   IsBackUpWHBooleanWhen 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.
   IsDAExemptBrokerBooleanWhen 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).
   NmOfIndividualObjectName of the foreign individual.
      FirstNmStringFirst name of the individual.
      MiddleNmStringMiddle name of the individual.
      LastNmStringLast name of the individual.
      SuffixStringSuffix of the individual.
   CitizenOfCountryStringRecipient's country of citizenship.
   USTINTypeStringTIN type of the recipient.
   USTINStringRecipient's TIN.
   ForeignTINStringForeign TIN of the recipient.
   IsFTINNotLegallyRequiredBooleanWhen TRUE, indicates that the beneficial owner on line 1 is not legally required to obtain an FTIN from their jurisdiction of residence.
   ReferenceNumStringRecipient's reference number. You can use this field to enter any identification number you have for the recipient.
   DOBStringDate of birth of the recipient.
   ExpiryDateStringDate of form expiration.
   PermanentAddressObjectRecipient's permanent address.
      Address1StringStreet address or PO Box.
      Address2StringSuite or apartment number.
      CityStringRecipient's city.
      ProvinceOrStateStringRecipient's province or state name.
      ZipCdStringRecipient's ZIP code.
      CountryStringRecipient's 2-character country code.
   MailingAddressObjectRecipient's mailing address.
      AddressObjectAddress information of the recipient.
         Address1StringStreet address or PO Box.
         Address2StringSuite or apartment number.
         CityStringRecipient's city.
         ProvinceOrStateStringRecipient's province or state name.
         ZipCdStringRecipient's ZIP code.
         CountryStringRecipient's 2-character country code.
   W8TaxBenefitsObjectTax treaty benefits.
      BeneficiaryCountryStringCountry where the recipient claims to be a resident for income tax treaty purposes.
      ClaimingProvArticleParaStringArticle and paragraph of the treaty benefits.
      RateOfWHStringRate of withholding.
      TypeOfIncomeStringType of income for which the recipient claims the treaty benefits.
      AdditionalConditionsStringAdditional conditions from the tax treaty benefits.
   SignatureObjectSignature of the recipient.
      SignerNmStringName of the signer.
StatusStringStatus of the extraction.
StatusTsStringTimestamp of the extraction status.
AvgConfidenceScoreStringAverage confidence score of the extracted form data.
LowConfidenceFieldsString []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.
InfoStringInformation about the extraction.
TINMatchingObjectTIN Matching information.
   StatusStringTIN Matching status.
   StatusTsStringTimestamp of the TIN Matching status.
   ErrorsObject []Detailed error information for TIN Matching.
      IdStringError ID number assigned by TaxBandits. It is unique for each error.
      NameStringName of the errored node.
      MessageStringError message.
ErrorsObject []Top-level request errors, returned when the entire request cannot be processed.
   IdStringValidation error code.
   NameStringName of the validation rule that failed.
   MessageStringDescription of what went wrong and how to fix it.
Request Json
SampleDescriptionAction
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
}
Response Json
SampleDescriptionAction
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
}